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


My colleagues in technology and I like to keep all the docs with the code in source control (preferably in Markdown, Gherkin or other change-control friendly formats), however we're a multi-stack shop due to a number of acquisitions, legacy technology stacks, etc, so we have multiple solutions:

1/ Almost everything in TFS/SharePoint, now migrated to VSTS in the cloud (not good for the OP), aka the full Microsoft solution - this works pretty well, including less-techie access and editing via the VSTS web GUI for requirements management, design reviews, etc. Project control is via Aha*, which integrates with VSTS ticketing.

2/ The Atlassian solution, Confluence + Jira + BitBucket Server, also being migrated to cloud versions (we like the cloud!) - thus far unable to hold confluence pages in BitBucket, so not really connected together, but a good UX with cross-referencing, and excellent for less-techie access. Aha again integrates with Jira for project control.

3/ The random document clusterf*ck - not my favourite approach but still rather popular, especially when documents or information are sourced from outside the business and helpfully emailed round the team(s), or dumped on a non-versioned shared drive (we're trying to kill this!). Some sanity is usually created through a common project document structure, and encouraging outsiders and their internal reps to feed into Aha as a common information point.

code of conduct - report abuse