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

I really like GitBooks. (see: gitbook.com) It reminds me of an old school SOP when they lived in three-ring binders and had handwritten content pages in the front.

Not sure what 'hosted on premises' means, so there's that :D

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 team uses Confluence within the Atlassian suite. Works fairly well for the intended purpose, and it's easy to use. Creating a page is more like creating a word doc than a wiki. I like it better, but those are the only two solutions I've ever used. ¯_(ツ)_/¯

We started with a wiki (since we were on GitHub, we used the one provided with our main repo). We eventually switched to using a separate repo containing only markdown files named meta for all of our documentation, including research, best practices, corporate how-tos like expense reporting, time off protocols, etc. We even had a page dedicated to the memes we use in chat, so new team members could figure out what the heck was going on.

We found using a markdown repo gave us a few advantages:

• Changes to the knowledgebase could use a pull-request model, allowing for come amount of discussion and consensus before they were added.
• Markdown is already familiar to everyone, and being git-based means you can access it offline through your cloned copy
• The team is pretty quick at writing markdown so it was useful for recording meetings and decisions in real time, and then just committing the change later
• Search - either using git grep or, since we were on GitHub, just a browser
• Developers are at the command line anyway so this was a familiar workflow

Disadvantages:

• It made is basically impossible for non-developers to contribute, or in many cases, to even access it
• Linking between pages is all manual (wikis and other tools generally do this pretty well)
• Link rot and page rot (but I think every tool is at risk of this)

The problem with wikis is when you want to relate your notes to your code (and ideally, that's what you want to do).

I created Code Story to address this issue. Have a look ! I'll post about it soon.

Our team of approx 60 devs are using Atlassian Confluence. The choice was really simple, since we had an existing wiki, and our company moved to the Atlassian suite of products.

We've also focused on documentation that describes behaviours of systems and across systems. So most of it actually reflects what the intent of the code is. Capturing intent and being able to track decisions / choices and motivations over time has allowed us to actually have useful documentation that allows the next developer / tester / ops / whoever to get up to speed relatively quickly.

It's also a wonderful source of group decisions / goals when starting projects, that give a lot of context into why code has been written in a certain way.

I'm not a huge Jira fan, but Confluence is super easy, straight forward, and quite intuitive in comparison.

We have tried with google docs, but that's never worked well enough. too ad-hoc, hard to navigate and discover things in the structure, and... It almost hurts to say it...Confluence has great Jira integration that makes life easier for us 😁

Right now I'm using Notion for personal notes, dumping some stuff into the github wiki, and putting stuff I may need to share into onenote (because the rest of the team is using it). Previous job we used 100% confluence, which was ok because it integrates well with jira.

All I want is a reasonable editing interface that handles markdown-like formatting, including easy code formatting, and a way to share with a team. Bonus points for easy linking to github/asana issues, even if I have to write the macro/shortcut myself. Notion is ok, but is really opinionated about how you'll structure your text and has a couple quirks/bugs that deeply irritate me.

We're using confluence with a template page hierarchy. Something like:

<Project>
    Getting started with <Project>
    <Project> Processes and Procedures
    <Project> Architecture and domain
    <Project> Operations
    <Project> Active Development Projects
    <Project> Planning
    <Project> Staff and Organization

The latest version of Confluence lets you copy the whole page hierarchy and do a find/replace in the title of the pages.

I'm not sure if Confluence counts as a 'large-ish setup'. It requires a database, and it is a java webapp, with all the infrastructure that implies. It hasn't been too bad for our team, though. On the positive side, it gives you a wysiwyg editor

Day job: team foundation server, team build, visual studio, sharepoint, office 365, onedrive. The integration between all the tools is very well done. Visio diagrams for architecture. If we were a small business, I'd push for visual studio team services.

Other job: confluence, gitlab, jira. Has giant gaping holes where features should be. Terrible integration. Just terrible.

Edit: doesn't really answer the question. A well architected file structure is great with appropriate office doc types, sharepoint as a UI with all the other integrations. The other company doesn't do much when it comes to documentation.

We use confluence. The hardest part I found about documentation is writing it. To encourage continued documentation, I have suggested in the past to at least create a page in your tool, prefix it with "DRAFT" and at least do a brain dump or even copy paste from past conversations. At least that way, the knowledge isn't lost. I've found that has time goes by, I eventually go back and start cleaning things up and eventually end up with some pretty clean documentation.

For personal documentation, I follow the same thing but with evernote.

By simply having the data somewhere, it can at least be indexed and searched even if it's ugly.