4 ms·
We use a git repository full of markdown files for out team's documentation and it works really well for us. Benefits include: * It's really simple for people
by scrapheap 2y ago
We use a git repository full of markdown files for out team's documentation and it works really well for us.
Benefits include:
* It's really simple for people to use and update.
* Everyone can keep a copy locally on their own machines in case they're stuck without access to the GitHub/GitLab instance
* People are much happier removing out of date information from it as they can always find in the history again if they need it
* Branches in documentation can be really useful when you're making big changes (or an individual wants to add personal comments to their local copy)
- 2rsf 2y agoWe use a variant of git+markdown as well, but it has a problem when non technical people want to contribute to it. Some non technical testers or product people don't know a lot about git or markdown making it non trivial to contribute.
- scrapheap 2y agoIf one of our less technical colleagues need to contribute they usually use the editing options in the GitLab project - they're already used to the interfaces as we make a lot of use of their issue boards. As a bonus most of them also pick up a basic level understanding of git, which helps them join in other conversations they didn't previously feel they could.
- mejutoco 2y agoI dont want to downplay your experience. IMHO there is enough markdown editors and visual guis that this is trivial. Even if the git repo is just commit everything to main. They might not even need to know about branches. As for markdown, it is so trivial, especially with previews anywhere, that this is a made up problem. I think these "non-technical" people can learn this if needed, and if they have the will.