4 ms·
The problem with documentation is that the infrastructure/tooling for it is terrible compared to the infrastructure for code. Documentation is often in external
by Nextgrid 6y ago
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).
- noir_lord 6y agoI 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.
- Nextgrid 6y agoIn 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.
- noir_lord 6y agoFor 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.
- __jem 6y agohighly recommend using plantuml, which allows you to version diagrams as text. the diagrams are super ugly but it's totally worth it.