This is number 3 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

Perhaps the worst aspect of being employed in the high tech sector is the lack of learning the lessons from those who have come before us. Rather than determining what’s "good enough" to deliver documentation requests, rather than evaluating what tools and techniques have worked in previous large-scale time-critical efforts, most corporate technical writing situations have evolved from the idea that technical documents are just a kind of written document, and what worked for business correspondence and school term papers will work for other use cases.

To skip this fate we must embrace tools and techniques which are simple in concept and use. (Simple in this context does not mean "trivial to understand" — these have depth and subtlety, and advances uses will require learning and practice.)

Tools

Most technical documentation needs can be satisfied by the Markdown content mark-up system. This text-file-based system is limited in capability, learnable in a few minutes, and lightweight. This document was composed with Markdown. (Markdown will be the focus of my subsequent commentary.)

Technical documentation with more serious design and formatting needs should consider using LaTeX, the driving force of modern document creation. In comparison to Markdown, this is unlimited in capability, learnable in a few days, and something of a heavyweight. There is nothing, I posit, that nothing can’t be typeset more beautifully with LaTeX. (If your work includes mathematical formulae, LaTeX is almost mandatory.)

Workflows

Your existing software engineering teams already use git for version control. Their workflow is:

1. Make changes with a simple text editor or all-in-one development environment app.
2. git add to stage the changes when they suffice to address a need (remove a bug, add a feature).
3. git commit to group the changes together with an explanatory comment (which doubles as release notes, by the way).
4. git push the modified files to the central code repository if changes are to be shared.

If changes need to be rolled back, git can do it. If the current state of all the files in the repository must be captured, git can do that (and a lot more).

That’s it. The combination of git and Markdown provide the horsepower behind creating and distributing technical documentation, from one-page instructions to book-length papers. The combination of git and Markdown also has advantages on the information-consumption side of things:

• Germane — Information marches along in step with code changes, becoming visible as the code is deployed through engineering, quality assurance, and finally, production.
• Effective — The code and documentation is kept in sync without any additional process. Developers do what they’re already doing, technical writers are exposed to the updated information at the earliest possible moment.
• Appropriate — Alpha- and beta-testers see the information as it matures, as the documentation is tied to the codebase being tested, and not before.
• Source of truth — Intertwining the code and documentation increases the reliability of the information and trust in the processes documented.
• Versioned — Versioning is native to the git workflow, providing both a much easier method for creating updates and maintaining every version of documentation without yet another human-managed process and the attached overhead costs of attention, speed, and timeliness.

This section is short, but that’s a perfect illustration that there’s not much to the necessary infrastructure. The rest is all technique, and calls for inspecting an example of git/Markdown workflow.