Has there ever been an internal documentation tool that developers like?
Comments
verdverm•48m ago
git + markdown is the way, especially in these agentic days
plenty of tools to turn that into html if you want
confluence is bloated an unweildy
Jira done well is actually nice
necovek•29m ago
Has anyone seen Jira done well? And no matter how it's done, it is always slow and bloated.
Confluence is slow but pretty simple, standard wiki otherwise. Obviously, if I had a choice, it'd be nothing Atlassian.
git+markdown limits editing to developers only.
verdverm•27m ago
Jira has improved massively the last 2-3 years, it's faster than GitHub now in my experience
The question was about developer documentation, so non-developers was put to the side in my answer. We are also now in the agentic age, so git + markdown is operationally much more aligned with the primary doc producer and consumer. We are more managers and editors these days.
necovek•7m ago
I have not seen the improvement in Jira: if anything, it only feels slower.
GitHub Issues today seem bloated too, so perhaps your frame of reference has moved backwards while you weren't looking and suddenly Jira is fast?
verdverm•1m ago
I use Jira daily for ~8 years, it has become faster in it's own comparison over time.
Jira is a highly customizable beast, it does matter how your Jira wizard sets things up
necovek•4m ago
I generally liked Python doctests: runnable documentation. It is really an amazing concept, only a step removed from literate programming IMO.
Two problems with it were that 1. often setup boilerplate overshadowed the actual essence of the documentation and 2. people abused them for e2e testing making for unreasonable reading (and slow testsuite runs).
verdverm•48m ago
plenty of tools to turn that into html if you want
confluence is bloated an unweildy
Jira done well is actually nice
necovek•29m ago
Confluence is slow but pretty simple, standard wiki otherwise. Obviously, if I had a choice, it'd be nothing Atlassian.
git+markdown limits editing to developers only.
verdverm•27m ago
The question was about developer documentation, so non-developers was put to the side in my answer. We are also now in the agentic age, so git + markdown is operationally much more aligned with the primary doc producer and consumer. We are more managers and editors these days.
necovek•7m ago
GitHub Issues today seem bloated too, so perhaps your frame of reference has moved backwards while you weren't looking and suddenly Jira is fast?
verdverm•1m ago
Jira is a highly customizable beast, it does matter how your Jira wizard sets things up