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.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
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
metafor 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:
Disadvantages:
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.