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

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:

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:

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:

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:

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.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.