Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

The problem with documentation is that the infrastructure/tooling for it is terrible compared to the infrastructure for code. Documentation is often in external systems (Confluence, etc) which lack version control and are hard to keep in sync with the code, and those systems are often extremely slow (especially considering all it does is handle text) and the user experience is terrible (no Markdown support, mandatory "wysiwyg" input, etc).


I just put a /docs directory in the root of the project and everything inside that is vanilla markdown.

It brings it under source control and if the person reading it doesn't know markdown they likely shouldn't be reading it anyway.


In all the places I've been that's now how things were and there wasn't any interest in changing it, so instead they kept going with a shitty and outdated Confluence/etc.


For the really high level stuff/business stuff that pretty much does have to live on confluence, I just link to the index page from markdown.

It's a little bit of work on my part keeping that bridge up to date but that should (imo) be part of a leads job.


highly recommend using plantuml, which allows you to version diagrams as text. the diagrams are super ugly but it's totally worth it.




Consider applying for YC's Summer 2026 batch! Applications are open till May 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: