Ask HN: How do you document long term products

[lobsang]

What are your tips or advice for creating product documentation which is useful over the long term.

Specifically I'm thinking of something which is well structred and can be used by new team members as a one-stop-shop for information about a product which would encompase design decisions, risk and the output of multiple projects.

What tools do you use and do you have any examples?

[sheveksmath]

This past week I set up our project's Azure DevOps wiki, uses markdown and allows you to generate graphs using mermaid.js - very nice, especially since it's harder to blackboard ideas remotely. Although we were initially just using a README file, it's faster to contribute to the wiki and is easier to manage more information with it.

But regardless of whether you have a fancy doc site or just a single README, I think it's important to just get information down that's actually important and written as clearly as possible, and then sorting by how commonly that information may be needed. It's also helpful to put yourself in the shoes of a junior developer or someone completely new to the project: does x make sense outside of this context? Oftentimes when we refer to some project-specific concept, we don't realize that there are implicit mental dependencies that someone must have before they can understand what we're talking about. The best documentation makes the fewest assumptions they can get away with about the reader's previous knowledge.

[cborenstein]

The goal of product documentation is that new devs (and future you) are able to get the info they need.

This doesn't mean that it needs to be entirely from a wiki.

In my experience, wikis are rarely up-to-date because 1) shared ownership === no ownership 2) too high expectations --> people publish less

I recently surveyed a bunch of devs on their knowledge sharing and learned that for most devs, private notes are actually more useful than wikis.

Private notes are easier to keep up-to-date because they can be messy and because they have a clear owner. You can then share them as needed.

Working on a product to help devs write better private notes and share as needed. The difference is that you write notes like you're texting yourself. This lets you be fast and loose. But then your notes are modular. Modular notes are easy to organize/share granularly.

[https://bytebase.io]

[afarrell]

1. Start With Why -- Make sure you know the audience for anything you write.

2. For developers, Default to markdown and easily-updatable diagrams (like mermaid.js).

3. Put docs as close to the Point of Action as you can so that someone can notice if they are out-of-date. Like putting your keys on a hook by the door.

[Keverw]

For one of my own projects I’ve just created markdown files in a GIT repo. Super simple but I guess sorta like your own private wiki.