Last Updated: 10 November 2015 10 November 2015
Technical Writing Services
Lasotell Pty Ltd has staff, associates and contractors in three broad categories of technical communication skills who can fill your writing needs. It is important to match our technical communicator with your task. The skill groups are:
- Production Writers - these people take material that is finished, except for final formatting for delivery. Tasks may include running a spelling check, adding headers and footers, printing, copying, packaging.
- Technical Editing - this category has a broad range of skills. At the bottom end, the writer can take material that is finished, or nearly finished, as far as the author is concerned, and edit it for grammar and general style. At the other end of the scale, the writer can take the first or second draft from the author and tidy it up in every respect, occasionally adding to the content by providing comments and ideas for the authors to consider. The difference between people at the top and the bottom of this category is the prior knowledge they have in the relevant field.
- Technical Authors - these people can create the material from scratch. They can act as ghost writers and do their own research, write their own material, edit it themselves (or better, pass it to someone in Category 2) and deliver it to the "owner" for content review.
What type of document development environment do you have?
Figure 1 shows an Environment Quadrangle that identifies four "extreme" environments for developing documents. Recognizing the true nature of your document production environment and where it falls in the Environment Quadrangle will give you a better idea of the types of technical writing skills you need. As you can imagine, a mismatch could ruin an otherwise recoverable or avoidable situation
Figure 1 — Document Development Environment Quadrangle
This environment is dominated by the complexity of the deliverable document. This environment needs mature processes if you want to deliver the product without losing your sanity or your shirt (that is, your company or department profit margin). This condition exists when the final product is being or will be produced in the following environment:
- Authors who can work co-operatively under tight time constraints; who are competent in the their field(s) and well disciplined in accepting and following pre-existing procedures.
- The document is data driven (such as in tabular data, financials) with little need for narrative text and yet it must be well presented, coherent and make a positive impression on its target audience.
- The document development team have little or no control over an imposed, rigid, complex format. The task complexity can overwhelm the authors and detract from the quality of the final document.
This is what everyone wants, but it is an "extreme" because the conditions necessary to produce it are usually not understood and so rarely achieved. Standard Output is achieved when the final deliverable is being or will be produced in the following environment:
- Well disciplined authors (understand and follow agreed good practice procedures) and are competent in their field(s).
- The text output is or will be a planned, continuous logical sequence of information with straightforward graphics.
- The people creating the document have total control over the delivered format (which effectively removes task complexity as a major development issue because the document developers can control it).
This is the environment characterised by chaos and garbage in, but a Standard Output product is required. It is the worst development environment because it is characterised by the view that the documentation is just a blankety-blank nuisance that has to be written with the least amount of effort from everyone involved in "real work". Magic documentation is what happens when the final product is being or will be produced in the following environment:
- The "contributors" who are undisciplined (no inclination to follow any procedure, except their own, which they see as the only way to do it) and have low writing ability (even though they may be highly competent in their field(s)).
- In the past, the document looks like at least ten people wrote it without talking to each other. The graphics make sense only to the people who drew them.
- Although the deliverable format is in the control of the document development team, it is usually turned into an unmaintainable art-form that is difficult to manage during development and impossible to maintain post-delivery. (The complexity of the task is not an issue in this environment; it is overwhelmed by the complexity of the environment itself!) Typically the contributors in this environment always know, after the fact, how to do it better next time, but never do.
In a few words, any job that has been left to a time when it is almost impossible to provide the necessary information at a credible standard. The typical response is to throw more people at it. Wrong — you have more chance of pulling it off with fewer, clearer thinking heads. You need a SWAT Team. But remember, Heroes don't come cheap. Before committing to this task, ask yourself these questions:
- Why are you doing this?
- Will someone literally die if you do not complete this task? (Let's get some perspective on the real importance of the matter.)
- Given that nothing is impossible for those who do not have to do it, how committed are the senior managers to finding a real solution that is achievable in the number of hours available to do the work?
- What are you trying to achieve?
- Will the company collapse if you do not succeed with this document? If so, maybe spending money on a panic-driven approach is the worst thing to do. There are other ways; talk to us.
Measurable benefits of using Technical Writers
The easiest to measure benefit is that engineers, for example, can remain focused on applying their skills to the technical information and not worrying about things like trying to explain it in plain language, formating, grammar and consistency. One technical writer can support several engineers and free roughly 20-30% of each engineer's time to focus on the technical part of the task.
Lasotell staff typically use conference-style dictaphones to simplify information gathering. This lets technical staff present their material in any way it suits them and to talk about it. We produce the written material from the tape. It saves the technical people's a large percentage of time. (One hour of tape turns into five or six pages of text that would otherwise have taken at least two to three hours of engineer time to write per page ). The engineer needs only to review and markup the output from the technical writer.
Specific Lasotell writing skills and functions
- Technical Authoring Function
- Original writing - all documents (specs, design, test, reports, tenders, presentations, white papers and so on)
- Preparing Standards interpretations
- Researching original material
- Sanity checking technical documents
- Interviewing technical staff for source material
- Technical reviews, code walk-throughs
- Editor Function
- Editing semi-finished work of others
- Proof reading the finished work of others
- Database activities - design, entry, reports (requirement tracing, for example)
- Documentation reviews
- MMI Advice and design
- User's advocate (ensuring the end user is being considered)
- Test Function
- Writing test specification
- Writing test plans
- Writing test procedures
- Writing test reports
- Running test procedures
- Raising Trouble Reports
- Verifying Trouble Reports
- Support Function
- Writing document manipulation utilities
- Debugging developed software
- Debugging utilities and tools
- Code cleanups
- Some software maintenance
- Advising on tool requirements and design
- Configuration Management - design and implementation
- Production Function
- Document production
- Delivery paperwork
- Covers and labels
- Quality checks
- Consistency checks
- Table of Contents and Index
- Library Configuration Managament
- Editing finished work