About document writing

Document Writing confusion

Writing a document is not like writing code. It is not clear about the good or the bad, and is not obviously correct or incorrect. For this reason, it is extremely painful for programmers who are familiar with code to write documents.

It's short. People say they haven't written it clearly, so it's not detailed; it's long. People say it's too trivial, so long, so there's no energy to look.

The leader said, "This problem is simple. Just give a brief description on two or three pages ." If you write only two or three pages, you will get approval.

It must be concise and detailed. This is much harder than writing code.

When we write code, what should we talk about refactoring? How many people have written code refactoring? A few. Which of the following programming languages does rebuild ten rounds? It's rare. However, it is normal to write a document, just a document, be restructured for dozens of rounds, dozens of rounds, or even a few rounds.

Writing code and writing documents are totally two realms. In other words, the salary for writing code is better than that for writing a document. The salary for writing a document is worse than that for writing a PPT. PPT is more refined than document, so it is more difficult to write.

Confusion in reading documents

The project description written by the business manager cannot be understood by the R & D manager; the requirement analysis written by the Project Manager cannot be understood by the developers, including the documents written by myself, haha.

Of course, if I say so, someone will be very uncomfortable. "Where can I not understand? What do you mean? Why don't you ask me? I will tell you ."

In particular, when new employees get the development materials they don't understand, they have to ask old employees who are impatient. "isn't the document clearly written? Not found? Here, here, isn't it ?...... Why not? Who do you not understand ?" The new employee quietly resigned after being depressed to a certain extent. The rest of the old employees complained.

I am also honest. I have never seen the end of most project documents from the beginning. even two or three pages of documents are skip-reading. In fact, it is not only a project document, but also a small one. I will skip reading almost all the books and materials, and it will probably end up looking at it. When it comes to a specific problem, read more relevant chapters. The problem is that key issues are often not expressed.

Generally, you can refer to the document structure. The structure is actually the skeleton of the document. A complete document is naturally available from the beginning to the end, but we will not see it from the beginning. Just like we look at a person, we will be surprised if the other person's arm and legs are less, but we will not see the foot from the beginning when facing the other person. If so, it's really rude. We only need to focus on it.

Document template compilation

It is unreliable to write good documents simply by relying on the author's writing and creation capabilities. After all, you are not a professional writer. The basic idea is "set templates". Software Engineering has a country standard document template, an ISO document template, and a cmme document template. However, any template can be used, not easy to set up, it is depressing. The reason is that those templates are just a shell and cannot be compiled without any instructions.

I think good document templates should follow the following principles:

Optional, can be deleted, can be filled, and can be set;

Allow the author to check the selected content items as much as possible. For example, the document confidentiality level can provide three options: "□normal □confidentiality □secret" rather than asking the author to fill in the content items, he may not know what to fill in;

The second is "deleteable", that is, the content can be deleted. The template provides some common document paragraphs as much as possible, such as the target readers of the document, you can list as many target readers as possible in the template, for example, "target readers include: General Manager, Technical Director, Project Manager, Customer Manager, requirement analyst, System Architect, the project leader "; the author deletes redundant content as needed during document writing. If the author adds content, it may not be easy to think about it comprehensively.

Second, it is "configurable". As mentioned above, the key content of a document is often not expressed with emphasis, and even the description of the key issue is omitted. The reason is that the author does not want to write it clearly, and there are often many things, I think about it for a while. In the template, list the content to be described as much as possible, for example, the project overview section, involving the project objectives, function scope, period constraints, contractors, project scale, and acceptance methods, list the items in the template one by one for the author to fill in, so that no content items are missed.

Finally, it is "programmable". After all, there is still a lot of content in the document that the author needs to write based on specific project situations. This work is creative and most difficult to understand, it is recommended that you refer to the previous documents when writing.

You may think that it is really good to have such a template. Is it easy to make such a document template? It is really not easy. It is not enough to organize document templates by the Project Manager alone. If the company has a project management department or a Project Management Committee (PMO) to handle this problem, yes.

Document Content Compilation

It is difficult to write documents. Here I will talk about my writing experience.

In the process of writing documents, the software I use most is not Word, while MindManager and OneNote are only used for final document arrangement and revision.

MindManager, as its name suggests, is a tool for thinking management. It can be used to draw mind maps, structure charts, and brainstorm ideas. When I want to write something, I usually use the brainstorm function of MindManager to knock out all the content that I can think of and related, then, we will summarize, add, delete, and orchestrate the content, and soon a mind map like the octopus will come out. This is actually the prototype of the "skeleton" of the document. I will adjust this image several times before writing the document until I feel it is perfect.

Of course, in the process of revising the Mind Map, relevant materials, text, images, and reference documents must be collected one after another. At this time, the OneNote software was used. It is one of the suites in Office2010 and is very convenient for data collection. It supports text-and-text mixing, can be extracted at any time, will be automatically archived, with the recording function, can be unlimited division of tags. If MindManager is building a "skeleton" of a document, it is "flesh and blood" of the document ".

After everything is done, we can use the relevant document template and fill the organized content in it. In this way, a complete, clear-thinking, and informative document will be released. Finally, it is typographical. This is Word expertise.

Postscript

I found that many of my colleagues use different document editing software, such as Word2010, Word2003, and WPS, however, it may cause some inconvenience during document communication. Why is it difficult to unify the software development tools but office software? For the reason, I think, in everyone's mind, "R & D management" is far inferior to "R & D.