In addition to writing user documentation for software and IT hardware, Cherryleaf also writes policies and procedures. In this post, we look at approaches to writing these types of documents.
A lot of policies and procedures documents are written in Microsoft Word and published as PDFs. Word is an application that everyone knows and has on their machine, and PDF is a format that everyone can view. There are, unfortunately, some downsides to this approach. People tend to print out these formats, as it’s easier to read the document that way than online; this means you have to ensure people print out the latest version, whenever the content is updated. From a writer’s perspective, it can be hard to reuse content across different documents, in the same developers reuse bits of code. Instead, the reader has to jump from one section to the next.
Designing content for reading online can help ensure readers are using the latest version, but there still needs to be the capability to provide a printed copy. You also need something that can be used by non-professional writers to create content.
So what are the alternatives to Word?
Here are a couple of ideas:
1. A wiki-based or wiki-like approach
You can separate the formatting from the content, and generate paper, Word and online versions. You can also have some embedded content (such as warnings) in pages. They provide easy to use authoring environments. The downside can be that it’s hard to make changes across the site – you have to change pages individually.
2. Markdown or AsciiDoc
You can separate the formatting from the content, and generate paper, Word and online versions. You can also have embedded content (such as warnings) in pages. They provide easy to use authoring environments, but they do not often provide a WYSIWYG view to the writer.
Content can be stored as text files, in a repository, so it’s easy for anyone to submit a suggested change. There are now applications that can provide content management, but otherwise you may be creating a bespoke solution for your situation.