I want documentation that is easy to update, can be backed up, and stays close to the systems and processes it describes. Markdown files with version control and a publishing step seem promising, but I worry that extra steps will put people off. What tends to work better for a team that changes its docs regularly?
Is a Markdown-based documentation setup too much hassle for a small team?
Asked by
clamdrifter
Answers
It depends on who has to make the edits. If most contributors are comfortable with version control, Markdown can be a tidy fit, especially for technical docs that belong alongside the related configuration or code. History and review are useful, and a publishing tool can turn the files into a readable site.
But if every tiny correction means syncing a local copy, making a change, sending it for review, then waiting for a build, people may avoid doing it. I’d keep the editing path as short as the team can support, and make sure the published version is easy to preview.
Reply to this answer
If low-friction editing is the priority, a wiki-style tool may be a better match. The main thing is to test the exact workflow, not just the feature list: can someone reopen a page later, does editing survive a long pause, and can the team export and restore the content?
Those checks matter more than whether the editor looks polished. A quick edit that disappears or can’t be recovered is not actually convenient.
Reply to this answer
I’d avoid choosing based on the tool alone. Decide who owns each kind of documentation, where it should live, and what makes someone update it when a system changes. If the docs are separate from the work, they can drift no matter how pleasant the editor is.
For a mix of technical and routine material, a hybrid can work: versioned files for documentation that changes with infrastructure, and an easier shared editor for material that many people need to maintain. Keep backups and a clear source of truth either way.
sidewayskiwi:
How do you keep a hybrid setup from turning into two competing versions of the same instructions?
Reply to this answer
A bit of structure can be worth the effort for critical documentation. Review and version history make it easier to spot risky changes and recover from mistakes. Still, requiring a heavyweight process for every typo is likely to discourage updates.
I’d try the proposed workflow with a few real edits, including one by someone who doesn’t work in version control every day. If the routine feels awkward in that small test, simplify it before moving the whole library.
Reply to this answer
Add your answer
Answers are reviewed before publication.
clamdrifter:
That’s my main worry. A few people are comfortable with version control, but not everyone who might need to update a procedure is.
tea.on.mars:
Then consider letting technical docs live with their systems while giving occasional editors a simpler route for operational notes. Just decide how those two sources stay connected so they don’t contradict each other.