re: Where do you keep non-code documentation, such as architecture explanation or research? VIEW POST


We use Confluence (along with JIRA and BitBucket Server) and it's a bit of a clusterfuck. No one really uses Confluence because it's extremely hard to find anything when there isn't anyone managing it and keeping it organized. It's a repository for a lot of documentation. Often times JIRA tickets and git commit messages are a far better source of documentation in the code than Confluence.

Other downsides to Confluence are cost, maintenance and lack of standard (i.e. markdown) support.

This says a lot about other options though: Everything else we've considered doesn't do any of this better.


Our Confluence turned into a total clusterfuck until we realized the importance of wiki gardening. I had to put on a bit of a deletionist hat, which helped, but the real win was developing a standard page organization format for documentation. Every project is laid out in the same way, with the same type of documentation in the same place.

Since search sucks soo bad in Confluence, the rigid layout guidelines made it useful again.


We also use Confluence (along with JIRA) and I agree that JIRA tickets and git commit tend to be a better source of doc to understand what components do. Confluence seems powerful but it's not intuitive and requires time to manage/organise.

code of conduct - report abuse