Writing and Designing Documentation

As I began writing and designing the documentation for a specific project, I noticed that I was a little less prepared than I’d like to have been. I delved into the project without fully preparing myself, and found that I had to frantically learn everything along the way. After browsing a ton of technical communication resources (websites, blogs, tech writing courses, writer friends), I concluded there’s not enough condensed information out there for people to use and learn from. Because of this, I decided to create a quick guide for people looking for help in creating technical documentation to be successful in their next project.

Before Writing

Before you begin to sit down and write and your documentation, you’ll need to first create a plan for yourself. This will significantly increase your chances at a successful project, and decrease the level of stress you’ll encounter along the way. The type of planning involved in this process may include learning what type of documentation you’ll be writing, looking to other documents for inspiration, determine what tools you’ll use, and figuring out what type of design works best for your documentation.

What Type of Documentation will you be Writing?

There are many different types of documentation you can write. To determine the best document for the specific project you’ll be working on, you’ll need to ask yourself the following questions:

• What is the purpose of writing the documentation? Knowing the why of your document is the first thing you’d want to ask yourself before writing. If the plan is to create step-by-step guide on how to operate a toaster, you’d use very simple language to get your message across instead of going into details about the specifications of the toaster. That would be confusing to your audience, which brings up the next question you’ll need to ask yourself.

• Who will read this document? The type of document you’ll write depends widely on who the document is intended for. A document intended for developers on how to build software would look almost completely different from a document intended for, let’s say, your grandmother trying to figure out how to use her new iPhone.

• Where is your documentation being displayed? Will your user guide be posted on a company’s website, or will it be kept in a folder to never see the light of day?

Looking at Existing Documents for Inspiration

Before diving into the project, I found it extremely useful to look at other documentation for not only inspiration, but to see acceptable standards of different types of documentation. While there is no “right” way, it would be beneficial to get an idea of what is already in existence. Below, I’ve provided a few examples to help get you started.

• MailChimp’s Patterns Documentation

• Digital Ocean’s API Documentation

• Stripe’s Documentation

• Rasberry Pi’s Quick Start Guide

• Visual Studio Code Documentation
  

Determine your Tools

To decrease confusion along the way for both you and the technical or documentation manager alike, you should determine what tools you’ll use before getting started. Here are a list of XML editors and authoring tools to make your next project a success.

Office Apps and Help Authoring Tools

Free: Libre Office, Google Docs, Zoho Docs, Office web apps, Help N Doc

Paid: Microsoft Office, Adobe Robohelp, Help N Manual, Author-IT, MadCap Flare

Creative Suite

Free: CamStudio, GIMP, Microsoft Paint, Paint.net, Jing

Paid: Photoshop, Illustrator, SnagIt, Camtasia Studio, FrameMaker

Desktop and Project Management

Free: Scribus, Zoho Project, Asana, Teambox, Slack

Paid: InDesign, Microsoft Project, Zoho Project, Podio, Teambox

Document Design Principles

When writing and designing documents, user experience should be a top priority. When your documentation is opened and read, the user should be able to find what they’re looking for without any troubles. The process of finding relative information should be seamless, on top of being easily understood. In order to achieve this, the following principles of design needs to be in place:

• Alignment

• Consistency

• Proximity

• Contrast

• White Space

Principles of Writing Great Documentation

Similarly, user experience needs to be a top priority when writing your documents as well. Below are a few principles of writing documentation that’s crucial to executing a successful project.

• Consistent

• Complete

• Accurate

• Concise

• Factual

• Organized

Finally Getting Started

It may seem intimidating to finally get writing; you may feel like you haven’t done a sufficient amount of research beforehand, or that you’re not doing things “the right way,” but if you’ve prepared yourself by asking and answering all of the pre-writing questions and adhering to both the design and writing principles mentioned above, you are indeed ready. Besides, if you come across any problems, a quick Google search usually answers any immediate questions you’ll have.

Do you have any additional writing and designing tips? Please share them in the comments below!