Ask HN: How To: Internal Documentation?

In my experience, this process is always subpar. There is no clear place to find documentation; even if it's there, it's often outdated.

I've been thinking about this for a while, and I feel like writing, reading, and maintaining documentation could get much smoother and, frankly, more fun!

Do you have any ideas on how to improve it all?

The first place was doing support in web hosting. All the layers worked well to create feedback loops. Think phone techs, stats, and engineers all working to drop queues. Very high turn over but they had the absolute best training staff I've ever seen.

The second place wasn't in web hosting, but was similar in rigor. The culture was generally more relaxed. They relied less on trainers but still had very good ones. Their docs were more well-maintained. The work was reasonably well-distributed until they were acquired...

Most places don't have trainers (quality or not), feedback loops or docs. Opting to learn while chasing the dragon, ignoring the hoard.

- There’s an onboarding guide that is usually only updated when new people onboard. If something is not right they raise it and their onboarding partner fixes it.

- When someone shares a technical document/RFC we add it to a central repository with a creation date on it. These are point in time and usually not updated but still useful for new hires.

- We sometimes do onboarding sessions to walk through the architecture, these are recorded and added to the central information repository.

Note that in the things I wrote above there’s a mix of up to date content and slightly outdated content, ultimately the code is the source of truth. It’s not worth spending time writing docs that no one is gonna read.

So it can be done. The how is less about tools and process and more about simply making it a focus. I consider documentation of how to work with the codebase to be as much a core feature of the product as anything customer-facing. It is maintained, tested, and updated as deliberately as any other feature, and we log bugs on it and call out missing updates in PRs.

I use the README in our primary repo to be the starting point, and link to other places as needed. I include all the pre-reqs and instructions to get running, without assuming anything is already on their system or they know anything about our organization. Or even what OS they are running. And I include a goal-based list of FAQs - How to add a model, create a new API endpoint, change front-end routing, create new front-end components, tie everything together into a new feature, etc. How we branch, how we interact with PRs, team standards and norms, etc.

Exactly what your docs say will vary based on what type of work you are doing, but the key is to make documentation a primary feature of the product, and treat it as such when testing and reviewing code.

1. At most one person is willing to create it

2. Nobody is willing to update it

3. Nobody is going to read it