Ask HN: How to maintain a killer product documentation page

5 pointskostarelo3y ago3 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 :)

3 comments

zkirill3y ago

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

superfreek3y ago

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

p0d3y ago

Good content and a good TOC.

j / k navigate · click thread line to collapse