Yesterday, I wrote:
“There are some activities that seem like they always could be improved. One is creating an authoring environment where professional technical communicators and other staff can work together.”
Writing online Help is different from writing some other types of content, in that it involves topic-based authoring. Content is stored in modular, re-usable and flexible chunks of information. By moving away from a page-centric, document model, you’re able to organise and present published information in many different ways. However, it’s a different approach to what many non-professional Technical Authors are used to. Unfamiliarity with this content model, as well as the tools, can make collaboration difficult.
What problem needs to be solved?
“Review cycles are often time consuming and take place in 1:1 scenarios over email. As a result, the process of managing, maintaining, and publishing technical documentation can be inefficient and expensive.”
Tom Johnson
Collaboration can be seen in different ways by different people. The main issue can be seen as:
- Making it easy for other team members to make comments and amendments. It’s about editing.
- Tracking and managing changes. It’s about version control and the audit trail.
- Making it easy to contribute content. It’s about authoring.
- Making it easy to amend the content at some point in the future. It’s about authoring.
- Working on different parts of the document at the same time. It’s about authoring.
- Making it easy to generate different outputs and versions. It’s about publishing.
Current tools
The popular Help Authoring tools do support collaboration:
- MadCap Software’s MadCap Contributor provides managers and subject matter experts (SMEs) with a simple, easy-to-use interface for editing and reviewing topics, making annotations, and updating content.
- RoboHelp’s “Create PDF For Review” option lets you create a PDF that reviewers can review with the free Adobe Reader. The PDF stores a tagged structure of the RoboHelp project, enabling you to import comments back in the RoboHelp project.
It’s also possible to work collaboratively, amend content, and track changes in Google Docs and Microsoft Word 365. However, word processors use a document-centric model, rather than the topic-based model Technical Authors need.
Other approaches
Let’s say these tools don’t meet our needs – what other options are available? There are a number of Cloud-based solutions emerging, but some organisations want to keep their data in-house, rather than on someone else’s computer. Let’s look at what else you can do.
direct Access to the authoring tool
Team members can log into the tool and make any changes directly. Some tools offer a simplified editing environment for occasional users (for example: FontoXML and FrameMaker’s simplified XML authoring environment. You could also customise and simplify the ribbon bar of your Help Authoring tool). Others use topic templates to make it ensure writers create content in a consistent way (Statemic, Kraft CMS and many content management systems).
Check in – check out
Help topics are stored as individual files in a repository, rather than in a database, and team members can check out files to their desktop. They can make any changes, and they can then check the file back into the repository. This approach opens up the possibility of them using an authoring tool of their choice, but it also means it’s harder to preview the topic in its published form, or in the context of all other content. The most common tool for this is probably Microsoft SharePoint. It stores previous versions of files, but it’s not always possible to compare differences between different versions of the same file.
Branching and merging
To quote Roger Dudler:
“Branches are used to develop features isolated from each other. The master branch is the “default” branch when you create a repository. Use other branches for development and merge them back to the master branch upon completion.”
This is a common method used in developing applications, and it can be applied to writing content as well. As it follows the same model as code development, it can encourage developers to contribute. One of the most popular versioning tools is Git. Help topics are stored as individual files in a repository, and again this approach opens up the possibility of them using an authoring tool of their choice.
However, contributors do need to understand how tool such as Git works. As this comic strip from xkcd illustrates, it’s not always easy:
Konrad M. Lawson pointed out another issue with branching and versioning:
“A related but more difficult challenge is the way in which text is the dominant form in GitHub. While other files such as images, sounds, etc. can be included in a repository, it is much harder to incorporate the versioning features, and the incremental improvement features that make GitHub so powerful when you are dealing with other kinds of content. It is easy to show the exact difference between two similar text files using a “diff” but the “diff” between a jpg image containing a dog and one containing a dog with a moustache drawn on it is just a bunch of binary gobbledygook.”
There are a number of authoring environments emerging that are based on storing content on Git, or the Cloud version, which is called GitHub. For example, Penflip.
Commenting only
Another approach is to have team members who can only comment on the content. They are given a copy to annotate with their feedback and suggestions. This feedback is collected by someone with an editorial role, who can decide whether incorporate any changes into the master document. This is often done using Adobe Acrobat and PDFs. You could also use Annotator to comment on HTML pages. Although this approach makes it’s easy for people to comment, it does rely on someone having the time and skills to implement those changes.
How do you do it?
What approaches and tools work for you? Please share your thoughts below.
Leave a Reply