How to write a good software document

today, I see an article about writing technical documents, try to translate a bit, turn it bad, please help correct. The text reads as follows:

I don't know if anyone will read or write technical documents as a hobby. I hate to do this, but usually we have to do it to solve the problem or introduce a technical product.

It's hard to write a good document. There are several forms of technical documentation: a basic overview, a high-level overview, step-by-step demos, auto-generated documents, and more. Consider the requirements of different users for your documents: different needs, different technologies, different learning styles. You will find that there is no format that adapts to everyone at the same time.

Audience Situation

The first thing you need to consider when writing a project document is the reader. The first thing an end user needs is a getting Started guide. While some technical concepts may be mentioned, the focus should be on the user interface rather than the background. If it is a programmer, he may want to get more information: How the program works, how the code is implemented, how to extend the code, and so on. Documents written for some users should not affect the reading of another part of the user, you may consider writing two separate documents, user manuals and technical documentation.

Several different types of documents

Jacob Kaplan-moss in his guide to how to write a good document, he mentions three documents: Tutorials , topic Guides , and reference guides .

Tutorial : Tutorials are important because this is often the first impression the user gets when using the new tool. As we've written before, there are a number of different tools that can help you write a good tutorial. If you want to write, Kaplan-moss recommends you write it quickly and easily, but not too easy, you can do a demo, to add relevant for each step.

Topic Guide : Kaplan-moss says this is the main content of the document. Although the tutorial provides a high-level concept, the topic Guide allows people who are interested to learn in depth, and the content must be detailed. Kaplan-moss mentions that, in general, books are better than official documents, but one advantage of the latter is that they are always updated.

Reference Guide : The reference Guide is intended for users who have already started but need more information. Customized for users who already know how to use the API, but need to find the exact function parameters or detailed setup information. It should be noted that the reference guide is not replaced by the tutorial and the General guide. Automatically generated documents can only serve as a guide, and if there is no additional writing, editing and organizing, it is impossible to solve everyone's problems.


While this is "technical writing," It doesn't mean that you should give up on literary, grammatical and spelling checks. At least check the grammar and spelling.


Original link: http://www.readwriteweb.com/start/2010/08/tips-for-writing-good-document.php

How to write a good software document