4 ms·
> What black magic do you have to cast to get devs to look at the documentation? Not use Jira and Confluence? More seriously, I have found that confluence is
by stock_toaster 3y ago
> What black magic do you have to cast to get devs to look at the documentation?
Not use Jira and Confluence?
More seriously, I have found that confluence is where documentation goes to die. Something about the tooling, the slowness, poor search, admin tools leading to overzealous compartmentalization, not-quite-good plain text format, awkward gui editing tools, versioning system, distance from the code[1]... something... just makes it not really great at being a repository for keeping documentation up to date, or easily usable.
[1]: eg. not using the same tools/editors to modify the documentation as you do the code
- sodapopcan 3y agoYa, there is some wisdom in "don't use Confluence". It's far too heavy for a wiki. Maybe it's fixed by now why should a plain text page show a loading spinner?? I'm personally a fan of one massive README with a table of contents for technical docs. YMMV. Also, definitely link the docs in the description and not the comments. I've found that you should never rely on anyone reading the comments (or re-reading them, at least). Any important info that is surfaced in comments should be moved to the description. Of course, if you're team isn't going to read tickets then that's just a plain problem.
- paulddraper 3y agoThere is truth to this. Notion, etc are far more pleasant, readable, and lend for better organization.
- smcleod 3y agoYeah confluence and jira both need to go away, both of them make it very hard to find information and feel like such a burden to use.