How to write technical documents

1. Preparation Preparation phase

The work in the preparation phase mainly includes the following points:

·Clear document requirements

·Clear document audience

·Define document scope

Before writing a document, it needs to be clear Documentation requirements. You need to understand why you want to write this document and what purpose you want to achieve by writing this document.

It is also necessary to clarify the document audience. The content is likely to be different depending on the audience. For example, documentation for developers and non-developers/ordinary users will have different organization of content.

Also define the scope of the document. Think about and determine what content or modules this document needs to cover and what content it will not cover. In this way, you will have some focus when collecting information later, and you will not be vague when writing.

Related recommendations: "php Getting Started Tutorial"

2. Research stage

Those who have experience in writing technical documents My friends will definitely feel the same way. If you don’t understand something, writing documentation for it is simply too painful.

So how can you avoid the pain when you encounter an unfamiliar topic that leaves you clueless? Of course, I just try my best to understand it.

But how to do it specifically? In short, it means collecting information. So how to collect information? The author believes that we can start from the following points:

(1) Research the relevant documents of more representative similar products or similar products to see how other people's documents are done.

When you don’t know anything, it is a good choice to learn from other people’s experiences and practices. By comparing the documentation of several products, you can establish a rough framework for the documentation you want to write.

It should be noted that reference is not a copy, it is only used to provide ideas; different products will have different structural planning of the document.

(2) Use the most effective methods to collect all kinds of information related to the document you are writing.

The collected information will likely become part of the published document after being excerpted and organized by Technical Writer.

There are many ways to collect information, such as Internet searches, questionnaires, interviews, experiments, as well as email discussions, reports, technical articles, etc. Which method to use requires detailed analysis. You need to choose a method that can quickly and accurately collect the required data based on factors such as document requirements, deadlines, and the richness of existing data.

On some writing topics, searching the Internet may not be able to provide you with almost any help. Even for this type of content, you can get some information from the developers. You can ask them to help provide information according to your needs, or you can get the information you need through development notes and discussions in the internal system.

For software product documentation, even if there is some technical information, the Technical Writer often needs to use it himself so that he can have an intuitive understanding of the operation steps and obtain first-hand information on document writing.

3. Organization document structure

When the data is almost collected, you can organize the specific structure of this document. Previous research on similar products may be done in Here’s a helping hand.

For common product usage guides, they are generally organized in the order of installation or use; for other non-guide documents, they should also follow a certain order or logic.

In addition, you also need to consider whether the document needs to be accompanied by pictures and whether it needs to use tables. If you need to add pictures, make it clear whether you need help from others or whether you need to complete it yourself. Drawing a more complex picture is also a time-consuming task, and the time spent must also be taken into consideration.

After you have a detailed document structure, you can proceed to the next step of writing.

4. Writing document writing

If you have done the first few steps well, writing will become very simple. You only need to fill in the corresponding content accurately. into the document schema. In this process, you need to write paragraphs or specific steps. This is a time to reflect on your language and writing skills.

Some technical writing books say that you don’t have to worry about grammar, wording, and punctuation when writing documents, and believe that these details should be improved in the Revision stage.

Expand your outline into paragraphs, without worrying about grammar, refinements of language usage, or 
punctuation. 
Writing and revising are different activities; refinements come with revision. - Handbook of Technical 
Writing

I have a different take on this. A qualified Technical Writer should have good language skills. The most basic details such as grammar, wording and punctuation should not be a problem that needs to be solved alone. Standard grammar, decent wording, and correct punctuation should have become a writing habit that requires no extra effort and takes up almost no extra time.

If the first draft is rough and contains many small details that need to be modified, this will definitely increase the workload and time cost during review, thereby delaying the document process.

Perhaps, this method can be adopted for large enterprises that have a refined division of labor and each person is only responsible for a small link. However, this does not apply to startups that are developing rapidly and require agile development of documentation.

5. Revision

After writing the first draft of the document, it generally needs further revision and improvement. Revision here refers to the modification after review, so this step can also be called: Review & Revision.

So who needs to review? Technical documents usually require two types of reviews from other partners, namely:

·Technical Review: From a technical perspective, check whether the description in the document is correct and valid

·Language Review: Check whether the expression in the document is concise and appropriate from the language level

After receiving feedback from the reviewer, the Technical Writer needs to make timely judgments and modifications. Any unclear points need to be discussed with the reviewer. Sure. After making the changes, ask the reviewer to take a look at it. If new problems are discovered, they need to be modified again. This review-revise process may be repeated several times, which is normal.

Of course, before asking others to review, Technical Writer can also review it himself to avoid low-level mistakes and not waste other people's time.

Haha, here comes the problem again~ Usually, people who have just finished writing an article are very reluctant to read what they have written. At this time, you can use some grammar and spelling check tools to assist. is you.

If you feel that you are careful enough and do not need gadgets to assist you, I admire your ability, but I still recommend using gadgets. Because you may also have times when you are in a bad state, when you are tired and doze off, and sometimes when you don’t know what the hell you have written... Don’t be hard on yourself and your gadgets.

6. Delivery Document Delivery

After the document is finalized, it can be published on the platform, which is generally easy to operate. Different companies have different document publishing platforms, and the writing tools used by Technical Writers are also different.

After the document is released, it does not mean the end. According to my work experience, even published documents may still have problems, whether they are documents from large or small companies. For example: undiscovered text errors, broken links, descriptions and steps that no longer match the latest products, etc. Technical Writer needs to keep up with product developments in order to update documents in a timely manner.

The above is the detailed content of How to write technical documents. For more information, please follow other related articles on the PHP Chinese website!