Technical Writing

Types of Technical Documentation

Product documentation

This includes guides, training manuals and anything that shows an end user how to use a product. Installation and usage instructions, often with illustrations, FAQs and knowledge base articles fall into this category. User guides are a popular solution for both external users and internal employees to get started on the usage of a particular product.

API documentation

API documentation is geared towards developers to show them how to integrate and use an API service. This is often accomplished following the OpenAPI specifications.

SDK documentation

Similar to API documentation, SDK documentation show developers and tech-savy users how to use a SDK.

Release Notes

These are technical documents that are created and published along with the launch of a product or a new update of it. They detail the features, bugs, improvements, and fixes that have been the focus of the last version of a product (often a software). They can be all the way from purely technical to nearly marketing documents, with just links to the actual commits and bugs interested by the update.

Engineering resources

A category aside is for resources that are written for engineers and technicians. These includes, and are not limited to:

  • BOMs (Bills of Materials) - a list of materials, components, and instructions needed to construct, or manufacture, or repair a product or service
  • Parts prints
  • Schematics - both of circuits and products

Specific tools are Arbortext, Teamcenter.

Process documentation / SOP

These are documents that show internal teams how to execute a task, use an internal tool, or follow a procedure. This is often accomplished with an internal wiki, and its structure is established by TWs.

Another name for process documentation is SOP (Standard Operating Procedure).

Project plans

More of a project manager task, project plans define goals and objectives of a project. They are created as a rather visual map of steps to take for a team in order to reach an objective or deliver a product.

Business standards

These are documents that set rules, guidelines, and benchmarks that a business should meet. They are often used during employees onboarding, as a teaching tool, and are written as a series of references that employees and the whole company adheres to. They may include company values and large objectives as well.

Marketing and Sales documentation

Not everybody agrees this is proper techincal writing. But if you do, then this includes white papers, case studies, blogs, tutorials, and in-depth articles showing how a product or service can help somebody’s business.

Market Requirements Documents (MRD)

These are documents that outline your potential customer base, their needs, and your competitors. They are part of a marketing plan. MRDs contain info about customer problems, their reasons, market opportunities, customer demographics, use cases, and competitors.

Request For Proposals (RFP)

This is a document that announces a project and solicits bids for it. In the end they are created to persuade customers and investors to buy or finance a product/service. Key points of this are the project overview, company background, project scope, and goal, often in a clear, visually-appealing, document.

Scientific papers

Unrelated to most of the above are scientific papers. While they can fall into the “white paper” umbrella, proper scientific papers are focused on actual data coming from a research, ratehr than starting from the point of view of a problem or use case. These are thorough, accurate, highly technical documents.

Terminology

  • Bottom-Up Processing
    • Processing a content from its smallest components to its largest ones. In a complex or not easily understood at first text, it may mean trying to understand the single words, punctuation symbols, and word order to comprehend, slowly, the whole content.
  • Complex Audience
    • An audience composed of people with different backgrounds, experiences, specialties, and expectations. A variegated audience.
  • Data Fluency
    • The ability to interpret, create, and communicate information in data. It is like the fluency in a language, which includes not only the understanding of words and grammar but also the capacity to express oneself in such a language.
  • Documentation Process
    • The sum of procedures and actions on how to create documentation.
  • Echo Words
    • Echo words may refer to a few different things. One is onomatopeic words, those which imitate the sound associated with them. Another meaning is words or phrases that contains two identical or very similar parts (“click and clack”). Lastly, echo words may mean words or phrases that often recurs in a sentence or paragraph.
  • Forecasting Statements
    • A mini outline of the major ideas and their order of appearance in the content.
  • Future Readers
    • Readers who will read content in the future, weeks, months or even years.
  • MVP
    • Minimum Viable Product.
  • Par Statement
    • Par stands for “Problem-Action-Result”. Par statements are precise, self-conclusive, and easy to understand pieces of content. They define a problem, the action to solve it, and the result of such action.
  • Parallelism
    • Also called “parallel structure” or “parallel construction”, is the repetition of the same grammatical form in two or more parts of a sentence. In practice, it means constructing phrases with the same order of subject+verb+object, in the same tense, so to result parallel to each other.
  • Phantom Readers
    • Real but unnamed readers. Those for which the documentation is not specifically written for but will read it too. In TW it is important to accommodate for their needs too, or at least be aware of their existence.
  • Problem Statement
    • A statement that conteztualize the problem a paper is addressing. It may include details on where and when the problem arises, who is affected by it, and what attempts have been made to solve it.
  • Technical Accuracy
    • The rate at which content is accurate, technically and/or factually.
  • Top-Bottom Processing
    • The opposite of bottom-up processing. In a complex text it means to observe its structure, differences in fonts, highlighting, and eventual symbols or images in order to understand it.
  • Structured Writing
    • Structured here means working with prefixed templates, often made in a markup language like XML/SGML/DITA. Structured writing means to structure the content around these templates.
  • Superstructures
    • A paragraph that provides an overview or summary of the main points covered in the body of a longer text.
  • Unstructured Writing
    • Unstructured writing opposes to structured writing in not using any template or prefixed content structure. Documentation written with an unstructured writing approach is freely decided on a case-by-case basis.
  • Use Case Diagrams
    • A diagram, often made in UML, that represents the expected behaviour from the user’s perspective of a system. It does not show the how, but only what the end user would like the system to behave.

Books

Writing and Technical Writing books

  • Information Architecture by Peter Morville at al.
  • Business Writing for Technical People by Carrie Marshall
  • A Guide to Writing as an Engineer by David F. Beer, David A. McMurrey
  • Docs for Developers: An Engineer’s Field Guide to Technical Writing by Jared Bhatti
  • Technical Editing: The Practical Guide for Editors and Writers by Judith A. Tarutz
  • The Product is Docs by Christopher Gales and the Splunk documentation team
  • Modern Technical Writing: An Introduction to Software Documentation by Andrew Etter
  • Revising Business Prose by Richard Lanham
  • Untechnical Writing by JoAnn T. Hackos
  • Technical Writing Process by Kieran Morgan
  • The Insider’s Guide to Technical Writing by Krista Van Laan

Styling and Designing Content books

  • Read Me First! A Style Guide for the Computer Industry by the Sun Microsystems Press
  • Don’t Make Me Think: A Common Sense Approach to Web Usability by Steve Krug
  • The Design of Everyday Things by Donald Norman
  • The Elements of Style by William Strunk Jr.

Style guides

While not universally implemented, often a style guide is chosen to be followed when composing technical content. A list of remarkable style guides you can get inspiration from are:

Online documentation and courses

Tools

Confluence

Often used for internal documentation, Confluence is an ok-ish tool for technical documentation. It has its quirks but lots of macros/plugins to customize the appearance of the content, and better format it.

Useful Macros/Plugins

  • Colgroup Tag + Column = great at showing two variants of code next to each other, it embeds the content into multiple columns. No header is supported but it can easily be added manually and formatted as desired.
  • Tabs Container + Tabs Page = alternatively to columns, when different version of similar content aren’t necessarily needed to be shown together, tabs can be used. This macro support headers and will show like browser’s tabs. Not much in the way of customization by default but CSS code is supported.
  • Section + Column = a default option to have the page’s layout split into columns.

Content reusing in Confluence

Multiple possibilities exist:

  • Include macro = can include a whole page into another.
  • Excerpt and Excerpt-Include macros = can include pieces of content into another page. The big limitation is that content can be included only once.
  • Multiexcerpt macro = works as the Excerpt macro above but doesn’t have the limitation of only including the content once.

An useful tip to organize content for reusing is to have a page per excerpt under the root of the wiki, not under any space to hid the page from searches. A special title, like a prepended underscore, can be used to differentiate these pages from the others. The Include macro can then be used to include content from this sort of mini-library of excerpts elsewhere.

All the excerpt macros can be set to hidden to hid them in the page where they are created but not from the page where they are included.

Tips

  • Categories are best used to connect and group similar spaces together.
  • Space and page layouts work with the Apache’s Velocity template engine.

Help & Manual

Help & Manual is an XML-based help authoring tool for writing help/manual pages.

MadCap Flare

One of the main editor for technical writers, MadCap Flare is only a part of a suite of tools for helping writers creating single-source documentation.

Oxygen

A suite of tools to create documentation from XML files. The main one is the XML Editor.

SDL Triton

A web content manager, semantic AI search and all around solution for content management.

RoboHelp

Adobe RoboHelp is Adobe’s effort for an help authoring tool.

Scribus

As an open source tool, Scribus is one of the most widespread. It is an XML-based software, which can import and export to multiple formats.

Framemaker

Another Adobe tool, Framemaker is specifically designed to handle a large amount of documents, structured or not.

Default DITA xml elements available in Framemaker

  • Topic = an element that consists of a single, self-contained subject matter.
  • Concept = generally speaking, the Concept element can be considered as a “specialized topic”. It should be used when trying to answer all that is necessary to do or achieve something, in a descriptive, usually, way.
  • Task = as with the Concept, a task is a specialized topic that answers how, procedurally, a task can be accomplished. It is more practical-oriented than a Concept and usually doesn’t include background info, as instead the Concept does.
  • Reference = another specialized topic, it differs from both the Concept and Task as it neither provides background info or a step by step lists of practical actions. It is meant to show general information about a topic that can be useful, without explaining a specific task or topic, but being largely just informative.

All the above elements are inserted into a new DITA xml file by selecting New DITA File in the menu and choosing the desired element from the submenu.

How to change background colour of a paragraph

  1. Select the paragraph
  2. Open the Paragraph Designer (Ctrl+M)
  3. Go to the advanced tab
  4. Change the colour, default is none, in the bottom right, under Pgf. Box

The colour will be by default applied to all the successive paragraphs. Set it back to none to cancel this.

Paligo

An XML-based, web CCMS for technical documentation.

Booktype

An open source publishing software. Web-based, it is still available for download but it is not actively developed anymore.

Clickhelp

A single-sourcing web-based documentation tool, with a large range of features.

HelpNDoc

A french publishing software, free for personal use, but only for Windows.

Markdoc

A content authoring tool based off pure markdown files. It powers the praised Stripe documentation.

MkDocs-Material

A documentation template based off pure markdown files, MkDocs-Material is an extension of MkDocs static site generator.

Redocly

A docs-as-code solution for API documentation, Redocly promits to generate full documentation from API reference files in seconds.

Author-it

An online content authoring cms built for eLearning courses and technical documentation.

Astoria

A DITA XML-based tool for content management.

Ovitas

A range of solutions for document management, publishing, and automation.

Document360

A software for building knowledge base and online help documentation but not strictly limited to those.

Doc-To-Help

A WYSIWYG software for document management and publishing

HelpStudio

Website

OfficeHelp

A lean content management system, complementing Microsoft Word.

Slate

A free and open source software to create API documentation.

Google Drawing

An helpful free tool to create diagrams and charts

draw.io

A free tool with plenty of integration, draw.io is for diagramming and illustrating software infrastructures especially.

Lucidchart

A tool for diagramming, Lucidchart is free for a limited usage only.

Other tools

A great list of further tools in the technical writing field is found here.

Scalar

Not exactly a tool as the others, but it is an handy tool to get quickly started with creating an API documentation site with an already existing Swagger/OpenAPI file. Open source, scalar can be used with a skeleton html file, which will load your spec file, and use CDNs to load everything else, setting up an API documentation very quickly.

Good practices and procedures

Developing a Doc Plan

At the beginning of a project of any size, writing down a Doc Plan to help starting it out and following a fixed schedule. The plan will consists of:

  • Product Description: a brief summary of the product
  • Audience: the audience the documentation is aimed to
  • Deliverables: name, format and descriptions of all documents, including media files if present, that will be created
  • Receivables: what you as a writer need from others (accesses, product versions, availability of experts that can answer your questions, templates etc.)
  • Style: what style guidelines will be followed
  • Tasks: list of actions required to complete the project and who is responsible for each of them
  • Tools: what tools will be used
  • Schedules: one for each deliverable

Optionally, and especially when working for external clients, these points can be necessary as well:

  • Copyright: who will own the copyright of the completed content
  • Cost: a breakdown of the costs for each deliverable
  • Disclaimer: add one that states that the ultimate responsibility for the accuracy of the content is of the client and/or developers
  • Terms: payment schedule, cancellation policy and other legal terms

Outline for good API documentation

  • Overview: API name, audience, purpose, usage examples, requirements for use, concepts, architecture, and architectural diagram
  • Quick Start: the basics of setting up the API and use it for simple tasks
  • Getting Started: a, possibly separated, section dedicated to setting up the environment to use the API. This may include the sandbox or testing environments, if offered
  • Tutorials: a few step-by-step tutorials about how to achieve the most common tasks with the API
  • Reference: all methods, path parameters, query parameters, endpoints, headers, sample requests, responses, sample responses, status, and error codes for REST API. For a platform API, every class, method, function, variable and so on

An useful AsciiDoc template is available on arc42 Github.

Writing a good tutorial

A tutorial is a lesson. It is not “do A then B”, mechanically, but should teach the reader how to do A and B by themselves. A tutorial must be:

  • Meaningful - readers should get a sense of accomplishment
  • Successful - readers should be able to complete the tutorial
  • Logical - the path readers follow throough the tutorial needs to make sense
  • Usefully complete - readers must encounter all the actions, concepts, and tools they need to become familiar with

Do not tell readers what they will learn. Tell them what we we’ll do and encounter. Assume they will learn themselves, you are not going to teach them, only showing.

Make sure that every step of the tutorial can produce visible results. Make these results be as early as possible in the tutorial, to give readers a sense of accomplishment.

Prepare users for possible consequences of their actions. Inform them if a command will produce a long output, or if it will take a longer than possibly expected time to run. Also don’t ignore lack of consequences, as in a message that should but did not appear, or a status that readers should reach but may not. Constantly inform readers of these possible situations.

Similarly, inform also readers of things that they should notice. A command prompt changes, or a new window opens etc.

Minimize explanations that are not strictly necessary to understand the tutorial. Do not explain choices made in detail, just inform the readers that we will be using program x or go with option y because of convenience/brevity/speed/whatever, and move on. There are other places where a detailed discussion of these choices may be done but they are not in the tutorial.

Similarly, ignore options and alternatives. Your tutorial should remain focused on the minimal steps necessary to reach the conclusion, not in all the possible ones that could lead to it. Take a path, and follow it, and only it.

Most of the above suggestions are extrapolated from Diataxis, and adapted by me for my own understanding.

ADDIE Model

An Instructional Design model that stands for Analyze, Design, Develop, Implement, and Evaluate. It is split into 5 phases, Analysis, Design, Development, Implementation, and Evaluation.

Breakdown of a tutorial

  1. Identify your audience
    • Developers (API, data models etc.)
    • Admins (Installation, setup, integration/plugins etc.)
    • End Users (How to use feature x, how to accomplish y)
  2. Determine the contextual layers that should be covered in the tutorial
    • Referential (glossaries, FAQs, API libraries, release notes, patch notes, admin/user guides that focus on the features only)
    • Procedural (how-to, installation guides, integration guides, support instructions)
    • Conceptual learning (planning guides, frameworks, best practices)
    • Workflows (cross-feature use cases for audience x)

Once both are identified, it is easy to create a skeleton of the desired tutorial.

Tackling a new technical writing project

A series of questions to help starting out with a new project, from the very beginning when nothing is known about it.

  • What is this product? Why would anyone want it?
    • Answer should come from asking SMEs and researching, not from a marketing standpoint
  • How does the product fit in the ecosystem, if at all? Does it have any dependencies?
  • Where can I acquire this product, and what versions exist?
  • How do I install the product? What are the basic configuration options?
  • What does a simple, start to finish, operation look like?
    • Any operation will do but it should take users from nothing to something, convince readers that they learned something valuable