Docs Proposal Process

1

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.

4 Likes
2

While I imagine this process will change over time, I think it’s a good fit for where we’re at.

I think posting a doc idea on Discourse is a good idea. It allows people more space to flesh out ideas if needed. It also allows for better async collaboration and discovery than Discord can provide (as you say, Discord messages can get burried in the chatter). I would say that it’s a good idea for people to also post in Discord though for visibility. At this point in the project, getting the attention/buy-in from existing community members and subject matter experts (SME) will probably be the biggest barrier for new contributors.

One issue could be alignment with project goals. E.g., on the last community call, it was expressed that case studies could be valuable, but only internally for now. We wouldn’t want to blast it out as marketing material (the normal use of case studies) until maybe Q2. We don’t want someone getting excited about SourceCred, doing a case study, imagining how valuable it would be to the project (which it is), but then not having the project publish it on the website, Twitter, etc. Another example could be a piece of documentation that is valuable, but we decide not to include in the official docs for some reason. For this reason, I think it would be valuable for the community (mainly you perhaps, but others) to keep an eye out for new contributors and take a more active role than usual, communicate with them, manage expectations, connect them to other contributors if they need them, etc.

As for more technical docs, that may be tough for contributors, as the subject matter experts (SME) are usually very busy. In prior jobs I was a technical writer actually, often in this position. The good news is that you don’t actually need to know the tech. I didn’t half the time. You just need to do a little reading up and then interview the SME, then get reviews from them or others capable of that. In this way, the SME roughly “authors” the doc, but doesn’t have to do 90% of the work (good use of time). The bad news is, it’s often hard to get that. Before someone embarks on such a project, to set them up to succeed, it would be best to get buy-in from the SME up-front. To get that may involve a bit of communication and in some cases social/political capital. This could be easier in SourceCred than in other jobs I’ve worked, as the SME and doc author should get Cred (and eventually Grain) for their work. But you may want to think about how best to allocate Cred in the docs process in a way that works for everybody.

2 Likes
3

Thanks for the in-depth response Seth. Here are my main takeaways:

  • The proposed system can work for now, but have holes in terms of Cred allocation.
  • Writing technical docs can be done without technical background, but involves speaking with SME.
  • Allocating Cred int he docs process needs to be fine-tuned (or really, plain old tuned).

I definitely agree that Cred allocation for docs needs some agreed-upon tactics. This could involve the platform we use to propose, approve, write, edit and review docs, but that involves finding a platform that works as a task-ticker, that supports writing/editing docs and tracks progress, and also supports discussion about docs, such as a voting system to see how important each proposal is to the community. I’ve looked into this and found that there were no perfect solutions, so my thought is that waiting for the Creditor may be the way to go.

As for technical documents being written by people who don’t understand the tech, I don’t entirely agree with that, as someone who has tried. I found that I created more work for SMEs by having multiple questions, and then follow-up questions, that couldn’t all be answered in one sitting, such as a meeting about the doc. One example is How to Set Up SourceCred. On the other hand, I was able to write the How to Convert Grain doc with the expertise of @panchomiguel. However, I was already somewhat well-versed in cryptocurrency for a non-dev, and already had a coinbase account. To conclude, I think tech doc proposals would need to be tagged with strongly recommended background knowledge/skills for those who’d like to try to author them.