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

FULL DISCUSSION
 

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)
 

You mentioned some non-technical documentation is in the repo too -- how have non-devs managed to deal with that? Do your non-technical teams use a different system for documentation?

 

Since we were a GitHub shop, we just had the greater product team (product management, customer success, etc) set up GH accounts, so that any URL to documentation was accessible. That at least gave everyone read-only access to the docs. We did end up teaching some of these people enough git-fu so that they could contribute, as part of their professional development, and that was well-received. But I did feel this setup was more dev-centric than I would have liked, and it ended up duplicating some information that was contained elsewhere, like in the employee handbook. But I have a violent allergy to both SharePoint and Confluence so this worked well enough for us.

code of conduct - report abuse