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).
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.
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).
The editor is execrable.
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
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.
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.
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?
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
[flagged]
[dead]