Ask HN: How to maintain a killer product documentation page

5 points by kostarelo 3 years ago | 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 :)

zkirill 3 years 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

superfreek 3 years ago |

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

p0d 3 years ago |

Good content and a good TOC.