I’ve been contributing to Radicle’s documentation for roughly a year now, and based on that experience, and thinking about where Radicle is headed into this year, with encouragement from @abbey & @shelb_ee, I wanted to start a conversation around Radicle’s documentation culture. And propose a few ideas.
A culture of documentation
Accurate and comprehensive documentation is valuable for any organization, especially in open source. We can all agree on that. But, in the end, documentation is seen as everyone’s problem, but no one’s job. This is especially true for a DAO like Radicle, where there is no top-down, cohesive approach to documentation—and might never be.
The big question I’m asking, and trying to answer is: How can a decentralized organization establish processes, precedent, and resources to help its teams and projects create valuable documentation?
The answer isn’t specific tooling, more technical writers, or letting each team/project manage their own process, as those don’t solve the underlying problem. It’s akin to Radicle governance—the tools and platforms can change, but approving a proposal requires knowledgeable people following agreed-upon processes.
If we can create a culture that people want to participate in and encourage, documentation becomes a source of truth and a powerful extension of brand values from the DAO down to its teams, projects, and people.
What we get from culture of documentation
- Users find answers to their questions themselves rather than pinging the
#supportchannel on Discord and interrupting core contributors. - Teams get information out of silos and onto a single version-controlled space to reduce institutional knowledge and gaps/misunderstandings between teams.
- We re-center the user (or developer) experience through writing documentation, ultimately helping us create better products and protocols.
- We all create a single source of truth for the state of Radicle for users, developers, community members, and governance participants.
- Every team has more resilience to contributor turnover, as documentation is no longer a single person’s job, but a shared effort.
Assessing Radicle’s culture of documentation
Overall, there is no consensus on what “good documentation” reads like or is structured, with many individuals and teams operating with different preferences. There is very little cross-team collaboration on larger documentation-related issues.
- Documentation is mostly seen as the sole responsibility of the Community & Governance team, with a few exceptions:
- RIPs for describing the Heartword protocol
- Developer documentation for Drips from the Funding team
--helpdocumentation in the CLI tooling
- Documentation is scattered across many platforms:
- Multiple GitHub repositories/websites
- Multiple repos on Radicle (
app.radicle.xyz) - Notion
- … and likely others
- There are no established processes for how core team members or contributors can contribute to the documentation or recommend changes.
- Very few core members and contributors have demonstrated the initiative to create a GitHub issue in the
radicle-docsrepository as a first step in resolving a documentation issue.
What can we do?
Here are a few steps we can take this year, sorted from strategic to tactical, to establish a culture of documentation within Radicle:
- Establish a Working Group, or at least an informal group of stakeholders interested in documentation, from Community & Governance, Clients, and Funding, discuss an ideal culture and set goals.
- Collaborate with Marketing on a Radicle style guide to formalize the strategies and techniques we adhere to while writing docs.
- Define the types of documentation Radicle needs—how-tos, explanations, tutorials, and reference—and create templates to simplify creating docs for users and/or developers.
- Document and optimize internal processes that help engineers contribute to and maintain docs with as little friction as possible.
- Host internal documentation education sessions to share resources, collect feedback, and optimize processes.
- Organize community events, like Documentation Days, to incentivize analyzing, triaging, and contributing on documentation.
Yikes—this got quite lengthy. Would love to