A path toward Radicle's culture of documentation

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 #support channel 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
    • --help documentation 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-docs repository 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

3 Likes

Hey Joel, thanks so much for this update. I would love to help with this effort. Happy to be a representative if that’s helpful. Just as an aside, it looks like your message got cut off at the end!

1 Like

Should we set up an open call to discuss this live with folks who are interested?

1 Like

Thanks a bunch for this.

First off, the best organized, managed, and - frankly - well working projects I’ve ever participated in have always had good documentation.

So I wholeheartedly agree with this post.

A few ideas that came to mind:

Apiary <> Docs Collab

@joelhans : you should chat with our grantees from Apiary. They’re doing 30-45min interviews with various Radicle stakeholders. The end goal is to build out recommendations on our governance and transition to DAO. I think your interest in documentation would be valuable input. CC: @anoukruhaak

Docs Organization

A few questions arise when thinking about how to organize docs:

  • Who should document something? The subject matter expert.
  • What should we document? Everything that isn’t self evident to someone who is a total n00b.
  • Where should we document something? Wherever makes most sense.
  • When should we document something? Whenever we have relevant and useful context.
  • Why should we document something? To avoid having people having the same question for eternity / save people time (time is life!)

Your point on friction is closely related:

  • Document and optimize internal processes that help engineers contribute to and maintain docs with as little friction as possible.

Totally agree here. It might be worth mapping out each language’s own automated documentation practices and work towards adopting these universally. I’m specifically talking about using Docstrings + documentation automation tooling.

As a concrete example, here is a function in a Python library.

The workflow for developing this software, would have gone like this:

  1. The developer would have developed a new function in a program. And at the time of developing it - with all the context in mind - will have added a docstring that describes what their tool/function does. For example, here is the source code on GitHub for that function above. Note that the docstring in the triple-quotes """...""" is the exact same content as what’s on the Docs page. How does that work?
  2. Some automated tool - in this case Sphinx - will read through the source code and create pretty docs. This lowers friction for documentation, all while taking care of important context and details at the time of creation. This is what creates [the nice Doc page here].

I think adopting this sort of workflow + supporting it as much as possible would help a lot. Should be something we encourage for sure.

In the example above:

  • Who documented it? The subject matter expert (i.e. the person building the thing)
  • What did they document? The high-level summary and lower-level details of how to use the thing.
  • Where did they document it? At the source (code), such that any future changes in the functionality would have to account for changing the documentation - keeps the document from going “stale”
  • When did they document it? At the time of development, while all the context was fresh in their mind (i.e. not reactively, but proactively!)
  • Why did they document it? So that people know how to use what they built.

Some basic things to engender that into the culture might include:

  1. First and foremost: supporting it technically like above to lower friction. Nobody wants to add tedious, manual steps to their workflow.
  2. Once a reasonable documentation workflow is supported per project/language, we start enforcing things like “No PR approval until docstrings completed.” Some of these sorts of things can even be caught by IDEs.

Working Group

Count me in.

2 Likes

I am hesitant about this initiative at this point in time. The reason is that we have an overarching open topic that will influence our direction and the culture we want to create. I am referring to the DAO transition, the CDO conversation, and most importantly, the relationship of the DAO (token holders) with the products that this community creates (for now that is radicle.xyz and drips.network).

If this conversation is focused on DAO-related documentation then +1. In that scenario, let’s align this initiative with existing discussions that might influence its outcomes, so it can be impactful.

If this conversation is focused on product-related documentation then I have many objections. Specifically:

  1. Regarding the team I lead (Drips), I don’t see the problem. Our decisions and research are well documented Drips Master Docs Index - Google Documenten and the same goes for our product & code docs.drips.network and What's a Drip 💧? · Drips docs. In fact, the main feedback we got previously is that we are producing too much documentation, but I don’t consider this a problem.

We are generally trying to stay very focused with regard to work prioritization, so I need someone to make the case about why this is the right time for us to further improve our documentation or change our culture.

  1. With regards to radicle.xyz I definitely think that we can do a better job with our documentation, but to my knowledge, the team is actively working on the new protocol. They are aware of the problem and are already prioritizing documentation (where the RIPs came from). In my opinion, instead of starting a different conversation, it is better to work directly with the team and help them out.

Overall, I prefer a model where people contribute directly to where development is happening rather than approach the topic from a high-level view. In my opinion, processes and culture that are “defined” by people outside of the core that is working on the product every day, runs a higher risk of lack of adoption for many valid reasons.

3 Likes

Thanks for your thoughts, @lftherios!

I agree this comes at a tricky time given the recent conversation about the relationship between the DAO and the product teams, even down to the content of various websites at the TLDs at which they’re published. Given that no one knows what this relationship will look like in a few months, it’s very hard to justify a “Branded House” (thanks @sean for that on Discord!) approach to documentation, even if everyone was onboard.

But I think it’s important to acknowledge that whatever DAO<->product relationship exists in the future, any approach to docs—unified or separate—inevitably impacts both sides of said relationship.

That’s why my biggest motivation isn’t to dictate how documentation should be done from a process perspective, because as you point out, Drips is already doing a fantastic job! I’m much more interested to see if the Radicle ecosystem can coalesce around some shared values and goals for what its documentation should achieve, which operate like waypoints for each time as they build a sub-culture around process. I think that’s enormously valuable.

And then people like myself, or some future documentation working group, would exist to take requests from the DAO/products that are looking to achieve those goals and provide assistance.

I hope that helps reframe the discussion a bit.


Let’s do it, @shelb_ee! We can chat in Discord a bit, and we’ll make sure to loop you in @sean!

And it looks like I can’t edit my first post, but luckily I only lost a half-sentence about being eager to have a longer discussion about “culture” and its impacts.


@bordumb, thanks very much for your response! I think your list of questions & answers is at the heart of this discussion. These have far more impact on culture than the tools one uses or what structure they follow, and while I like your answers here, I think even the process of unifying around these would take a lot of discussion and back-and-forth!

Who should document something? The subject matter expert.
What should we document? Everything that isn’t self evident to someone who is a total n00b.
Where should we document something? Wherever makes most sense.
When should we document something? Whenever we have relevant and useful context.
Why should we document something? To avoid having people having the same question for eternity / save people time (time is life!)

If and when we do have an open call to discuss more, discussing and codifying these could be the first agenda item and deliverable.

2 Likes