Recently, I spent some time updating (or, in places, writing from scratch) the onboarding docs for the engineering department at my job. Since I don't think I'm particularly good at this, I decided to come up with some guidelines first. After a few iterations I was able to articulate the mistakes I tend to make, and putting them into words helped to come up with solutions that felt exciting.

Here they are.

---

Community-maintained documentation tends to become more chaotic over time. Here's some guidelines to help keep that manageable.

1. Write for specific audience

Figure out an idealized reader profile and write specifically for that person. You can assume some preexisting knowledge, but keep it accessible - if you're writing engineering onboarding docs, write for a junior engineer. Make sure to explain non-trivial context and try to avoid jargon.

2. Keep it evergreen

If specifics are likely to change upstream (e.g. in third-party library, or in a different internal package), point to upstream documentation instead of copying - this helps to keep maintenance to a minimum.

3. Be wary of conflicting information

If documentation you wrote contradicts itself, clear it up. If it contradicts other docs, refer to Rule 2.

4. Prioritize essential information

It's a manual, not a manifesto. Be thorough, but get to the point quickly.

5. Use GitHub + Markdown for engineering docs

The best tools are no tools, second best are tools that you already use. Maintaining docs requires version control, review process, and rich formatting - engineers already have all everything they need, and they use it daily.

6. Be mindful of publishing work in progress

It's okay to iterate on a live document, but before being merged to the main branch it needs to make some sense to the reader (see Rule 1), and not contradict existing knowledge (Rule 3). If you're still unsure if it does, it's likely that you're not done yet - keep it in a draft branch, ask for reviews, use your writing as a thinking tool.