Document writers in the development team

Author in the development team Original article address: http://www.uml.org.cn/bzgf/200801255.asp

 

 

Generally, each development team has one or more professional technical document writers who write technical documents for their products. However, not all companies have dedicated technical document writers. If you have to compile a technical document that is associated with your software product, remember the following things in your mind.

Analysis required

The first thing most technical document writers do is analysis, which can be divided into object analysis and task analysis.

Object analysis

When conducting object analysis, you should clarify who this technical document is intended for, that is, who will read this technical document. In addition, are you writing application programming interface (API) files for other development teams in the company? How do developers from other companies do it? You should learn how much people who have read your technical documents know about the internal process of product development and what data you can use and what data you cannot use in the company?

It is possible that you are writing technical documents for the end user of the product. You need to figure out whether these users use computers as cainiao or experts. Are these users of different types or their backgrounds different? If you are not sure about these situations, here are some ways to help you determine these situations. Talking to a service group or technical support team member in your company about these issues can help you understand the situation of those users through their experience. Reading news groups and email lists related to this product or similar products also gives you useful information. You can even conduct a survey on your website, or directly distribute the survey to those registered users to learn the situation. However, in doing so, we need to let these people know that you are serving them so that they can get more feedback.

Task Analysis

Task Analysis includes analyzing how readers will use these technical documents. Is this technical document written to guide users in installing software products? In this case, you need to focus on each step of the installation process. Is it an application programming interface (API) file compiled to facilitate other programmers? In this case, you may need a benchmark format to split the application programming interface (API) component into several forms of logical arrangement, this allows programmers who need to read this document to easily obtain what they need.

Sometimes it is better to combine tasks with relevant references. The instructions can contain references, which are attached as independent content to the instructions. Another good way is to add skills, warnings, comments, tables, data, and other content to this instruction so that you can more vividly describe the relevant content, simply using a large amount of text can easily make readers feel dull.

Add graphical comments to technical documents

It is very important to add tips and warning content to the technical documentation, so as to avoid confusion between your readers and other instructions or reference materials. Take a look at the manuals or technical manuals prepared by others, and you will be able to get a lot of examples. In typical cases, adding borders around the tips and warnings you have added, or marking them with eye-catching underscores, is very helpful for your readers. Adding graphics to the article is also a good way, especially when you warn readers about some things, the graphical content makes the warning clearer and deeply impressed.

Note the wording of the Technical Document

Another important aspect of technical documentation is your wording. If your document is intended for beginners or people without technical background, you must analyze the knowledge of these readers. This is very basic and important. Because you don't know whether these readers really understand the abbreviated words you reference. To prevent your readers from having a headache with these words, you must use the full spelling words or add an abbreviated vocabulary. Is there a simpler way? The vice president in charge of the market in the company may not know what API is, however, if you write an API as "a set of tools that can help software designers make the software they develop can talk to the software we develop", it may seem very expensive. However, in this way, readers who have no technical background can better understand the meaning of the API.

For those professional technicians, you can use the terms (that is, you can use the stacks, threads, and other words) and write these words at the same time, you don't need to explain it again. However, if you are more familiar with the acronyms you use than you are not sure, you must follow the instructions in explaining the acronyms and keep up with the completed spelling. Do not over-use those lengthy words to show your vocabulary. Try to use simple wording that can describe the problem. By doing so, you will be more impressed with your readers, rather than wasting their time searching the dictionary. For professional technicians and non-professional technicians, you should write documents in this way to achieve good results.

Maintain document consistency

Finally, let's take a look at the importance of keeping the document content consistent. At the beginning of the article, you should decide whether to use the length unit of the rice or the length unit of the imperial system. In some subtle aspects, you should ensure consistency. For example, if 5 MB is used before the article, 5 MB should not appear after the article; you have to decide whether to use 5 feet or 5'. You must pay attention to these issues. When you use a variable, this interesting situation occurs: when you use the variable content, you use the "variable = definition of value" format, will it still use the form of "variable = example value?

Another thing to note is your use of fonts, because users may need to do some input work. Some users use an equal-width font, such as courier, to allow users to input data. In addition, you need to use "underline" or "bold ". Which form can be used depends on the habits of your career, but generally, you only need to maintain consistency of the usage in your articles. When writing a file, you should put a blank sheet of white paper on the side, so that you can record the usage that should be consistent before and after, so as to facilitate subsequent queries.

Conclusion

It is good to have a full-time technical document writer to create the technical documents you need. However, sometimes for some reason, only software developers can write these technical documents on their own. Although not a professional technical document creator, you should still pay attention to the problems mentioned above and apply these details and precautions to the preparation of technical documents, in this way, you and your users can write technical documents that are available and easy to read at any time.