This is number 5 of a five-part presentation:

• Writing About Writing — Technical Documentation
• Why Everything You’re Doing In Technical Writing Is (Probably) Wrong
• The Flying Car Era of Technical Writing Tools and Workflows
• An Example of git/Markdown Workflow
• The best part of using git and Markdown

Ease of adoption

Because both git and Markdown are currently used by your technical staff and Markdown is supported by common applications like Slack and Google Chat, adopting these tools in creating technical documentation is no great hurdle — it’s easy to extend what you already have in place.

Automated content generation

Because Markdown has such a simple structure, it’s easy to have computer programs perform much of the content-gathering! Over the years I’ve written "glue code" to automatically (that is to say, without human intervention):

• assemble software release notes from git log code commits
• populate a wiki with the release notes
• email the release notes to product managers and engineering managers
• create bug-tracking tickets for offshore quality assurance teams
• repeats these actions both on a time schedule (every Friday) and when triggered by external events (there’s a code commit with a pre-release label)

All of the above were beautifully formatted with Markdown. The unrewarding task of manually crafting release notes every week has been off-loaded and the engineers can do (wait for it) engineering!

This computational generation of documents with Markdown formatting vastly improves staff morale, generates error-free and consistent results, and does so each and every time it’s needed.

Perhaps it’s not up there with flying cars, but a happy and productive staff is a satisfying second best.

Conclusion

A git/Markdown workflow can productively upend existing, less productive, ones. Responsibility for content gathering is pushed to those in-the-know while responsibility for content design and distribution continue to be that of the technical writers, who provide the human context around providing consumers of technical documentation. Dependence on local files, aging proprietary cloud storage systems and formats, and their technical support is removed in favor of a faster, simpler, and free workflow (which is already in use by your engineers).

git is used widely in the software development community. Your technical staff probably live in git.

Markdown is also widely used, and is supported in common applications like Slack and Google Chat.

In the end, getting information to readers is our purpose, and any tools and workflows that help us do the job in an efficient and timely manner are the big win.

You can help by lifting your workflows out of the dark ages. That is all.

Read More…

Following are some useful resources to learn more about the topics I’ve covered.

• An online Markdown editor/previewer, dillinger.io obviates the need to download anything to learn, view, and modify Markdown.
• John Gruber’s original Markdown introduction at Daring Fireball.
• An interactive, step-by-step Markdown tutorial at markdowntutorial.com.
• mundimark presents a comprehensive list of links to Markdown libraries, services, editors, tools, cheatsheets, etc..

Should you want to do a test implementation of this process in your workplace you know whom to ask. :^)