A path toward Radicle's culture of documentation

📜 Archive 🌻 Community
4

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