Hey folx. I’ve done a lot of thinking on how to create a docs review process, and am realizing there are many pieces to the puzzle. I’d like to start with a bite-sized chunk: docs proposals. In this post I ask for community feedback on the process of proposing a doc, and how to go about finding an author.
Where to Propose a Doc You Think Could be Valuable to the Community
Currently, docs, their descriptions, and doc ideas are kept in the Docs Index. Personally, I have not seen anyone interact with or use the docs index in some time (please speak up if I’m wrong!). If someone feels passionately enough about a doc that they are willing to bring it up (to the docs lead, a specific branch, or the community), perhaps the need to document the doc’s traits is unnecessary, as progress will be made by whoever is authoring it. If we feel that there is community need for such a space, where docs can be referenced and not fall through the cracks, does the Docs Index do that for you? If not, what do you wish we had instead?
How and Where to Propose Docs and Weigh How Valuable the Community Would Find a Doc
Our current tools are Discourse, Discord, GitHub, and word of mouth (meetings and asynchronous communication). I believe the best strategy is for doc proposals to use a mix of Discourse and word of mouth.
Why Discourse and Word of Mouth
Word of mouth is a way to see if anyone feels passionately about what’s on your mind, and allows for in-the-moment collaboration. If you’re chatting with a team member and bring up an idea, this can provide immediate feedback, such as how much work your doc might take, what kind of experience you’ll need to write it, and who else might be an expert to reference.
Discourse provides a more in-depth way of explaining a doc while reaching more people and receiving feedback. Discourse feeds often provide information you didn’t know you needed, and thus saves you the time and trouble of finding out after already having written a doc. Although one cannot guarantee that they will receive feedback on Discourse, if they bring it up in a meeting, the Did a Thing channel, or the Review Requests channel, this community has shown they will reply to topics they find important. If the community feels that Discourse is the best route, I will create a Discourse template for docs proposals.
Why not Discord and GitHub
GitHub is relatively inaccessible, and doesn’t seem like an appropriate platform for doc proposals, as proposals would mint Cred, and this could be gamed. Discord allows for posts to get lost in threads, and many people don’t see every post made.
Deciding Who Will be Involved in Writing Said Doc
If someone creates a Discourse post and receives enough community feedback that they think their doc proposal is worth investing time in, the next step is deciding who will write it. Many doc ideas come from non-devs who don’t have the background to write technical docs, but would benefit and grow from the docs existing. Posting a docs proposal on Discourse could involve listing it as “looking for an author,” “looking to co-author,” “looking for tech support” or “confident to draft alone.” This process would be for authors and their supports, not about reviewers. If community members are willing to assist, they can either comment on Discourse (likes would receive them Cred, which would help with receiving Cred for writing/supporting docs) or message the post author directly to ask more in-depth questions. If the post author has certain community members in mind they think could be useful, the Discourse post would be a way to lay out their idea and let their potential supporter consider the doc and its work load on their own time.