from Hacker News

Ask HN: How to maintain a killer product documentation page

by kostarelo on 6/3/22, 3:00 PM with 3 comments

Sometimes I'm being impressed by a very thorough, well structured, always up to date documentation page.

Stripes', Slacks' and Jiras' documentation pages are the first three that comes into my mind (I'm sure people will have different experiences but still I'm sure lots of them will agree with me that these are exceptionally good documentation pages).

I've never been in an organisation where we were maintaining such pages and I'm not sure what is the process of writing them. On the contrary, my experience have usually been a state where the product requirements, the actual end product and the documentation being somewhat out of sync.

How would you describe the process of maintaining a great product documentation page?

Thanks :)

  • by zkirill on 6/3/22, 10:28 PM

    We generate a static website using Hugo and a documentation theme. [1] Non-technical members of our team can use Markdown easily and publish changes on their own schedule thanks to a very simple but sturdy CI/CD setup (GitHub Actions and NGINX).

    Stripe's documentation is way over-engineered and wasteful IMO, and probably requires a massive team to maintain.

    [1] https://github.com/alex-shpak/hugo-book

  • by superfreek on 6/3/22, 3:13 PM

    It's all about putting in the work. Not much programming expertise required.

  • by p0d on 6/4/22, 9:11 AM

    Good content and a good TOC.