
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.<p>Specifically I&#x27;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.<p>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](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.

