Writing Technical Copy – Getting the Format and Tone Right
At Daily Posts we have specialist and generalist technical writers. Our clients often find it hard to frame putting together a brief. In this piece we outline some of the ideas to help you establish a smooth technical copy writing process.
So you’re on the lookout for a technical writer to create a guide or technical document, but ironically you’re the one in need of guidance right now.
Don’t worry, it’s perfectly normal. In fact, give yourself a pat on the back, because most people skip the necessary research and then become frustrated when they hire the wrong person for the job.
Technical document creation is a complex art that requires significant domain knowledge, and not just combining words together in an engaging way. You may need more than a generalist; although a highly skilled generalist may be able to get the job done. Knowing exactly what you need from any new type of copy is hard. With technical copy the difficulty goes up a notch or two.
Just as a framework will help your chosen writer in their task, it can be useful to ask yourself some questions so that you can have a framework to make your decisions. Here are some questions to get you on track
What is the Purpose of the Document?
This is the very first thing that you need to ask yourself.
The answer should be pretty obvious. For instance, if you need a product installation guide then the purpose is to demonstrate how the end user can install the product.
Figure out what the purpose of your document is, and keep that in mind. It will play a role in how you will answer the next few questions.
James Cummings, CEO, takes a look at briefing technical copy.
If you need help getting technical copy written then get in touch with James today. He’s available on the numbers below, on firstname.lastname@example.org and on Skype YesDailyPosts- Sign up here if you are ready to get going or want a consultation.
UK: 02380 970979
US (646) 679-7971
Who Are Your Readers?
The people that will be reading the document should be at the forefront of your mind as you set forth on the copy writing process. They will determine the format and content that you have the writer include.
You will first want to specify if it’s a front-end or back-end reader. End users and customers are examples of front-end readers. These readers will only need to see information pertaining to the features and functionality of your product. A back-end reader needs more complex copy, to help them understand the processes and procedures that enable the system to work as it should.
There are also technical documents that are produced for business and IT purposes; technical specifications, use cases, change cases and so forth. A lot of the time this content will be used to demonstrate how you want something to work, what features you want it to include, and how you intend to bring it all together. This content may be presented to developers, programmers, business analysts, and other stakeholders.
What Language Should Be Used?
Aside from the prmary language of the document, and whether you need the document to be translated or not, you will also want to consider the complexity level of the document and voice.
Layman terms may be necessary if you are taking the technical components of a product and turning them into an installation guide or specifications booklet for the end user. On the other hand, highly technical terms would be required when dealing with developers, engineers and anyone knowledgeable in the domain. There is no point making things complex for the sake of it, but the writer must be able to write to the level of the reader.
What Should Be Covered?
You should do a detailed outline, or briefing document, which covers all the information that should be present within the document. What to cover is really driven by the purpose of the document and the type of reader. Break the tasks or systems that you are writing for down into component parts, tasks, steps or chapters. Make the structure clear so that the writer stays focused, but help them understand how everything integrates together too. You should budget for significant research time so that the document author can really get to grips with the subject matter. This will ensure that what you are delivering is usable for its purpose, and that it’s not going to confuse the reader.
The outline and answers to the other questions will be invaluable guidance for the guide/technical writing expert that you hire. The writer may also benefit from interviewing you, or other stakeholders in the project. Ensure that they have access to the documentary and human resources that they need to do a great job. This means introducing them to the team and pre-empting in the introduction that they may need information from the various stakeholders.
What Standards Must Be Followed?
The type of technical document that you need written should provide clear guidance on which standards need to be followed.
For example, if you need a patent application filled out then it must be done in compliance with patent application form standards.
ISO standards are often used in technical documentation. While this used to be unnecessary, it is quickly becoming a requirement to comply with these standards. So you should have an understanding on which ISO standard your technical writer will be writing to.
What Format Is Required?
There are numerous types of technical document formats. The main formats include Darwin Information Typing Architecture, DocBook, and S1000D. You may want to read up on the differences between these and find out which is most suitable for your project.
Take a process approach to your project and ensure that your chosen writer has the intelligence and inclination to do what they need to do to get the job done. A track record writing technical information may give you confidence, but a discussion on your project will also help you to identify whether they have the mental agility and motivation to deliver what you need to the level that it needs to be done.