Technical Writing ProjectsDocumentation • Manuals

Technical Writing Definition

Technical writing is writing or drafting technical communication used in technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, medical, consumer electronics, biotechnology and forestry. Technical writing encompasses the largest sub-field within technical communication.

See my recent technical writing projects:

Technical Writing Overview from Literature

Through my studies in technical writing, both modern and contemporary, I’ve discovered that technical writing has changed in many meaningful ways since it was first introduced as a field dedicated to the creating user manuals. During the I980s our concept of writing documentation changed from creating tutorial and reference standards to creating "information products” that supported use by computer users. Now, even these virtual manuals themselves have become outdated, with internet search and curation giving up instead “dynamic semantic clusters” (Baker ch. 3) of information. Modern technical writing involves creating breaking manuals into small tasks that provide that information to users clearly and simply and to make it easy to find.

“Like a compass on a journey, tasks provide direction.” Developing Quality Technical Information: A Handbook for Writers and Editors Ch. 2)

Process and Standards

The standards of technical writing now call for task-based articles using best practices from both content strategy and user experience design (UX) to create content that considers the user audience with every word. The focus should be on “the user”, and great effort should be taken to get to know the user. With a clear understanding of the audience, writers should answer the questions that users have, help them complete their tasks, quickly and accurately. “Technical information is information about a technical subject usually for a particular audience and for a stated purpose.”(Handbook ch. 3)

The Information Development Cycle

Since the docs that are now being created involve heavy involvement with the software development industry, the new industry-standard (according to Gales, Gentle, Etter) suggests technical writing that a cycle that resembles that of software development with researching, writing, testing, and editing phases. Christopher Gales codifies the information development cycle in the book, “The Product is Docs,” modeled after the systems development lifecycle in systems and software engineering.

The first phase of a technical writing project will require investigation of the product itself, through an equal amount of exploration and discussion. Throughout these sessions, notes are taken which will make up a draft of the docs. These will be reviewed and tested with usability research and internal review before being revised and published on a platform chosen by the company.

Publishing Platforms

The publishing platform can take many forms. In my recent projects, I have created user help portals at the recommendation of Etter and Gentle using static site generators. Sphinx with Python and Jekyll and Hugo are all used for this purpose. XML DITA with Adobe Framemaker is also a popular way to merge docs into versions that can be placed on both paper and web platforms. Even simpler still, sites like Gitbook and Confluence can allow developer generated documentation. Since there is no visible industry-standard, I’ve set to familiarizing myself with all the various tools required in addition to my reading.

View my Annotated Bibliography with Key Quotes