Published on

Effective Technical Writing - Mediums

Authors
  • avatar
    Name
    Danny Mican
    Twitter

Technical writing has a number of common mediums. Each of these mediums has different properties which make it suited for different types of technical writing and knowledge transfer. It's essential to understand each of the common mediums and their properties. Some of the most common mediums for technical writing follow:

  • Document - Freeform technical writing posts, such as HTML, Content Management Systems, Confluend or Google Docs, etc
  • Email - Gmail, Microsoft Outlook, etc.
  • Messaging - Such as Slack, Google Messages, Microsoft Teams, etc.

These mediums range from media rich, in the case of a freeform Document, to media constrained, in the case of Messaging. Documents also accomodate longer writings than size constrained messaging.

Common Mediums

Documents

Documents are the swiss army knife of technical writing, supporting rich media, variable length content and collaboration. Documents are well suited for all writing purposes. Documents lend themselves well to:

  • Tutorials
  • Blogs
  • Decision documents
  • Collaboration documents
  • Project plans
  • Notes

One thing to watch out for is document length. Documents accomodate any length writing, but technical writing that is too lengthy will easily lose readers interest. Documents are also well suited for collaboration, where multiple people are working together to write. Most documents support concurrent writing and editing as well as comments.

Email

Email is an excellent medium for targeted text-rich updates. Email is media constrained, making it difficult to format and interleve messages without customer design. Email is also poorly suited for status updates and collaboration. Email threads are cumbersome to navigate and visualize. Collaboration is much better suited for Documents or Messaging.

Email contains both a subject and a body. Most often readers only interact with the subject before clicking on email, making it critically important to getting the subject correct. The subject needs to clearly convey the purpose of the writing in a way the target audience can clearly understand.

Messaging

Messaging is a media and text constrained format. Messaging is a freeform blob of test which exists in a "channel" or in a "thread". Examples of messaging are Slack, Microsoft Teams, and Google Messages. Since messaging is text constrainted it's also important to get the content correct and to clearly convey the purpose of the writing in a way the target audience can clearly understand.