Wherein I present a five-part series on producing modern technical documentation with the git & Markdown workflow that’s already being used by your technical staff; aimed at technical writers and managers.

Table of Contents

• Writing About Writing — Technical Documentation
  • Introduction
  • What is Technical Writing?
  • About Computer Programming and Programs
• Why Everything You’re Doing In Technical Writing Is (Probably) Wrong
  • Good News
  • Modern Demands Of Technical Documentation
  • The Current Rushed, Disorganized Chaos
• The Flying Car Era of Technical Writing Tools and Workflows
  • Tools
  • Workflows
• An Example of git/Markdown Workflow
  • git Workflow
  • Markdown Workflow
• The best part of using git and Markdown
  • Ease of adoption
  • Automated content generation
  • Conclusion
  • Read More…

Introduction

My forté is writing about computer programming and computer programs. Throughout my software engineering career I was the person who took pains to write notes alongside my software and to write manuals which described

• the techniques used to build the programs
• the operational steps needed to install, configure, run, and troubleshoot

Writing was rarely in my job description, but it’s a vital part of the software ecosystem, and I had the bookworm background to make a go of it. Decades later, it’s what I do.

‘Begin at the beginning,’ the King said gravely, ‘and go on till you come to the end: then stop.’ — Lewis Carroll, Alice’s Adventures in Wonderland (1865)

Following that sage advice, we should start by identifying what exactly is technical writing.

What is Technical Writing?

Technical writing typically describes the specifics germane to a hard science usually intended for those with some grounding in the science (or at least the science of sciences). Some notable examples include:

• Relativity: The Special and General Theory, Albert Einstein (1916)
• The Art of Computer Programming, Donald Knuth (1968)
• Sociobiology: The New Synthesis, Edward O. Wilson (1975)

Technical writing is a discipline completely separate from popularized science books written for the laity, intended for those without advanced scientific education (or any scientific or critical thinking experience). Some notable examples include:

• What Is Life?, Erwin Schrödinger (1944)
• The Soul of A New Machine, Tracy Kidder (1981)
• A Brief History of Time, Steven Hawking (1988)

Scientific fiction — as opposed to science fiction — covers deep concepts in a compelling narrative, exposing readers to the framework underlying the physical (or digital) world. Some notable examples include:

• Cryptonomicon, Neal Stephenson (1999)
• Going Postal and Making Money, Terry Pratchett (2004, 2008)
• The Baroque Cycle [3 volumes], Neal Stephenson (2003-2004)

Science fiction, lastly, is a good tale draped in the trappings of science without any of the narrative concepts required to be realistic or currently possible. Some notable examples include:

• Foundation Series (7 volumes), Isaac Asimov (1951-1993)
• A Canticle for Leibowitz, Walter Miller (1959)
• The Hitchhiker’s Guide to the Galaxy, Douglas Adams (1978)

About Computer Programming and Programs

As my technical writing experience is mostly centered on computer programming — (Real-Time Monitoring And Graphing Of Ping With GNUplot) or specific programs (on the web, GNUplot, and published paperback, Internet TV With CU-SeeMe) — my writings about writing will center on creating documentation about those topics.

"…there is a tendency in many armies to spend the peace time studying the last war…" – L. Schley, The Military Engineer (1929)

My personal and professional life has been immersed in one or another software development cycle since 1977. Over the decades I’ve seen clients repeatedly make very costly errors — both with time and money — with the best of intentions. Learning from those mistakes is the foundation from which I’ll build my opinionated comments.

The truth of the matter, given the constant demands for a rapid software development life cycle, is that there is rarely (if ever) any "peace time", and the lessons of the "last war" on documentation are already out-of-date with the fleeting pace of technology.

It should be heartening to learn that modern technical writing doesn’t require a never-ending sprint on a treadmill of rapidly-obsoleting tools in an always-submerging workflow of doom. The vast majority of technical writing needs can be done with tools already in use by your software development staff, tools that are both free to use and free of proprietary encumbrances, tools that work on every computer operating system.

Next, let’s examine why everything you’re doing in technical writing is (probably) wrong.