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

Unless your document technical writing has been informed by software engineering techniques, you are probably mired in one of the following scenarios:

• Artists Slowly Creating Beautiful Works — You have the luxury of a very mature software product and a long release cycle, giving your staff artists the unhurried space to craft absolutely beautiful tomes with proprietary typesetting software and a long series of editorial and content meetings. Document consumers patiently wait for the grand, even opulent, release events and time is never of the essence.

• Sisyphean Scalability Rapid-Development Woes — Just as Sisyphus was said to be forced for eternity to roll an immense boulder up a hill only for it to roll down every time it neared the top, technical writers working for start-ups with very rapid development cycles are constantly chasing never-ending revisions of standalone documents, usually shared via emailed chapters or common cloud drive storage. The inability to determine exactly what was changed, a lack of version control, duplicated work on document copies, and a lack of time to do these challenging tasks results in poor-quality, ugly documentation that’s always out-of-date and late to the readers, be they beta-testers or paying customers.

In these common scenarios, the tools deployed are costly (Microsoft Word, Google Docs, Adobe PageMaker) and the techniques used (shipping around of documents, using document mark-up that’s mostly manual (or via poorly-implemented styles)) result in a miserable, frustrating, Sisyphean task.

Good News

The good news is that there are tools available that are:

• both free to use and free of proprietary encumbrances
• work on every computer operating system
• have centralized style formatting for consistency
• can be integrated with the versioned software development workflow already in use by your development teams

Part of the issue is that there’s no aggressive, critical evaluation of what’s "good enough" — what are the core needs of technical document creation and what software and workflow best addresses those needs.

None of what follows is new. The problem is generally that the decision-makers of corporate document policy are not those who have to live with the consequences.

Modern Demands Of Technical Documentation

The robust pace of the modern software development life cycle places the following demands upon technical documentation (and technical writers):

• Availablity — Various document consumers, within the company and externally, require on-demand (sometimes) 24/7 (sometimes emergency) access to your documentation.
• Scalability — The sheer number of APIs and deployed services creates a large knowledge base, one which can’t be managed and updated using static, standalone document tools, formats, editing techniques, and workflows.
• Timeliness — A dynamic environment dictates that we eschew the traditional workflow, of (say) quarterly releases, in favor of a workflow with very frequent updates as code becomes available and features mature.
• Neutrality — Accessible for editing to all technical staff, readable by all consumers, and not beholden to proprietary platforms and document formats.
• Egalitarian — Pushes responsibility for details down to those subject-matter expert (often those who are writing code) rather than creating a workload funnel for those charged with creating technical documentation.

The Current Rushed, Disorganized Chaos

Im looking at a Google Document containing an imported Microsoft Word chapter as I write this, but the following applies to many corporate document set-ups:

• Disconnect between code and documentation — Having documentation separate from the code being documented, and outside of the typical software engineer workflow, means that:
  • the work of documenting is always an inconvenient chore
  • the content freshness lags behind the existing codebase
  • standalone documents are moved out of their drive locations and copied ad nauseaum, becoming orphaned and no longer the document being updated — a state which becomes practically (and legally) precarious as the stale information is acted upon to support platforms, triage issues, used for remediation efforts, and by external developers to implement functionality.
• Fighting evolving functionality — much of the existing corporate writing depends upon (for example) Word-only features such as progressive nested section numbering, which isn’t supported by Google Docs (and isn’t manually maintainable at any scale).
• Incoherent competing style guides — A recurring challenge is the look-and-feel consistency across documents, an issue made more frustrating with competing evolving style guides among disconnected, orphaned files.

The key to reforming badly-performant (or failing) efforts is to liberate yourself from antiquated tools and workflows and adopt modern tools that’ve been used by your overworked software engineers for decades.

Next, let’s examine the flying car era of technical writing tools and workflows.