Online groups, winter 2012
Service-level agreements
For technical communication work, a member was asked to identify a service-level agreement (SLA). The technical communication work is the development, the publication, and the maintenance of online help and user guides. The member gave two examples of possible metrics:
- The difference between the estimated time and the real time for a documentation task
- The number of help topics that are produced in a month.
The member thinks that these metrics are not very useful, and he asked for advice about how to identify a useful SLA.
A member who worked in a development department had an SLA with the support department. The SLA had things such as these:
- Answer an e-mail message about a customer problem in 2 hours.
- Analyse the problem in 4 hours and specify whether there is a problem with the code or with data.
- Correct a problem with code in 1 day.
- Correct a problem with data in 3 days.
The member thinks that something similar for documentation is possible. SLAs are about correcting problems in things that customers use. Therefore, SLAs are applicable to the maintenance of documentation, not to the development of documentation. The SLA was primarily about the duration of time that was necessary for a task, not the amount of time that was necessary for a task.
A member supplied a set of metrics that her company supplies to customers. The customers evaluate the technical communicators and the documentation. Metrics and SLAs are different. Usually, SLAs have metrics to make sure that the agreed service levels are supplied.
An SLA between two commercial organizations usually has penalties for performance that is not satisfactory, as shown in https://simply-docs.co.uk/Service-Level-Agreements/Service-Level-Agreement-Standard.
Some organizations have internal SLAs. Sometimes, to have effective penalties between departments in the same organization is difficult, but it is possible. For example, if a department does not conform to the SLA, then possibly department members will not get a bonus.
Single-sourcing
An organization is thinking about single-sourcing with Adobe Technical Communication Suite 4 (www.adobe.com/uk/products/technicalcommunicationsuite.html). Before changing the production methods, a member wants to know how other people use it.
Before you choose a tool, specify what you want to achieve. What are the important differences between the necessary output types? How many people will create the documentation? Who will review documents?
Adobe FrameMaker is very effective when there are many versions of text in one file. You can use conditional text to hide or to publish different sections, and you can use variables to change text such as product names. Another member agrees, but gives a caution that complex conditional text can become a difficult maintenance problem.
An organization started to use MadCap Flare for single-sourcing (www.madcapsoftware.com/products/flare/overview.aspx). The technical communicators had to import all the content from the existing help, manually correct the HTML, and then set up styles for print and online documentation. Much time was necessary, but now the documentation can be output easily as PDF, HTML5, and other formats. Probably, for Adobe Technical Communication Suite 4, a similar method is necessary. Most of work will be to import files and do the set up. When new content is created, you must think about all the output. For example, think about where page breaks will appear for print versions and how this will have an effect on online versions.
A new user of Adobe Technical Communication Suite 4 and structured FrameMaker wrote that initially, Adobe Technical Communication Suite 4 is 'bewilderingly complicated'. An organization must make sure that sufficient time and money is available to set up the software. Ideally, use an expert who can explain how to start. After the software is set up, adding content is moderately easy and logical.
RSS feed