Alternatives to Word and PDF for policies and procedures documents

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.

See also: Cutting and pasting content into Word documents – Is there a better way?

 

5 Comments

Rahib

Newbie tech writer here. What about help authoring tools (https://en.wikipedia.org/wiki/Help_authoring_tool). They work much better at publishing help documentations, including the wiki style approach you mentioned, and making edits isn’t as hard. I’m partial to HelpNDoc.com myself because it’s free to use, and is very similar to Word. Thoughts?

Ellis Pratt

They do, but the disadvantage is their sophistication can make them hard for non-professional technical communicators to use. This means there can be a bottleneck in the process. Some tools, like Flare support version control systems such as Git and source content from Word. However, developers may feel more comfortable using markdown or a browser based authoring platform.

Niels Grundtvig Nielsen

> You also need something that can be used by non-professional writers to create content.
Really? I’ve worked in companies where non-professionals tried to write procedures, and the results were generally useless. Most of them were unworkable, inconsistent or both …
I’m producing more and more in DITA, where (of course) the Task topic is an ideal framework for procedures; deliverables are usually WebHelp, which allows good-enough print output. My preferred IDE for DITA – XML Mind, though I guess other IDE will support the same options – lets me generate other output formats including .pdf and .xhtml

Ellis Pratt

I would contend the vast majority of policies and procedures are written by managers in an organisation, rather than by a professional technical communicator. Even if a procedures writer is used, the content needs to be kept up to date, and those minor changes are usually done by the process owner themselves.

Rahib

Hmm, well yes, I suppose learning a new software is an added headache for a manager, or someone who’s doing this in addition to their regular job. Yet there’s always some learning involved with a new task isn’t there? Managers need to figure out the wiki and markdown formats too.

Admittedly, a lot of programmers and developers would have previous experience with markdown.

But I agree with Niels that documentation written by non-professional technical communicators are problematic. There are best practices everywhere, but there aren’t really any internationally accepted standard practice when it comes to documentation. I suppose DITA would be the closest standard.

This is actually part of the reason I suggested HATs. Most seem to come with some form of template built in that writers can follow, and it does allow for separating the formatting from the content as you put it. Some (like http://helpndoc.com/ which I mentioned earlier) are quite easy to use. 3 months in and I’m pretty happy with my level of expertise. The more professional products like Flare and Adobe’s tools are a bit intimidating to get started with.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.