Tianxia Articles (Wang Wei Gang May 2004) 1 Problem introduced programmer to write documents, this is a truth that is quizs. The Tang Dynasty poet Jia Island once said: "Two sentences for three years, a tear". Even the genius like Jia Island, I have to spend three years, so it is easy to write, there is nothing to cry, sadness, let me, do you have these lack of art cells? Of course, the technical document is very important. Good documents can not only guarantee the quality of the project, strengthen exchanges and communication, but also have the utility of inviting the boss to display the work. But think about the programmer of documents in order to cope with ISO9001 external audit, or to keep the CMM3's gold signboard - facing requirements, use example, data flow analysis, object-oriented design, database design, specification , Test plan, configuration management plan, configuration item change control, installation manual, training manual, user manual, online help, online help, acceptance report, project summary, etc., the programmer is not interested, no power This kind of fillings, climbers, make a sentence, and the cost of the body. Some people say: write code, the program is the "battle" of the real knife, how many code is to occupy how many new positions, exclude how many bugs have eliminated how many embraced enemies. Can you write a document? The writing document is at the logistics work of the battle. It was originally written by the films in the movie. Wasted the limited life of the programmer in the write document of unlimited long and infinite emptiness, not worth it! Really worthless? For this kind of thing, it is still nothing to have a problem. It is to know that in the technical field, any of the biased, emphasizing how a certain issue will make the proposal will be easily refuted by the conclusion of evidence. For example, some people think that the technicians don't have to write documents at all, their argument is that large-scale software companies like Microsoft have employed a full-time document compiler. As far as I know, even in Microsoft's project groups, in addition to user manual, online help, etc., the documentation related to end users is generally written outside the full-time user experience, other technical documents, such as specifications. The instructions are still to be completed by the program manager and developers. In addition, different types of projects have different requirements for document compilation: Similarly, in Microsoft, IE's usage manual can of course be written by people who are good at business writing, but like DirectX SDK. This type of product for developers, you can imagine how you don't understand how to write DirectX SDK user manual? Moreover, it is not that each software company has a strong empirical document compilation personnel, in the country, small enterprises, due to the limited project investment, most technical documents of software products still need to be project managers and programmers Parents. I don't want to repeat the importance of technical documentation here - until today I think that the document can have no programmer only in Zhongguancun in the 1980s - I just want to say, since everyone knows the importance of technical documents. It also hids a difference between writing documents, then, with it says "fear" written documentation, it is not as good as diving, and studys the method of writing a good document. We are not Jia Island, but we don't have to pursue the famous articles of the earth, weeping ghosts like Jia Island. Perhaps, just master some specific types of documents, compiling the law and compiling methods, and continuously experience the fun of writing documents in practice, we will disappear with the fear of writing documents. Today's cases and software products are related to the user manual. The "User Manual" mentioned here refers to the technical documentation provided by the end user, printing or electronic, for software product installation, configuration and use.
Usually, the user manual for development tools, development kits, libraries and other products is also known as programmer's manual or development guide, but the same user manual, and the user manual for ordinary products such as IE, is also a technical documentation for end users. This article discusses the list of objects. Many fanatic enthusiasts of open source software believe that Microsoft's products that do not open source code and open source software are simply a high quality "information garbage". Whether we are correct, but as long as it compares Microsoft products and open source products user manuals, most people will consciously draw such conclusions: It is no wonder that Microsoft's products are popular, it is no wonder that most open source products can always Mobilize the ultimate consumer - the user manual of these two types of products is not on the same grade! Indeed, the documentation of open source products is not high (here is common phenomenon, do not rule out the existence of certain special cases), which has been the industry's consensus, but what is this? Don't worry, let's first see two actual examples. The first example is a libbt project from the open source community SourceForge. The project's goal is to provide programmers with a library that supports BitTorrent download (which is what we often say ". I downloaded the libbt version 1.0 version from the home page of libbt (http://sourceforge.net/projects/libbt). After decompression, I found that there are so many documents that can be calculated as the source code and configuration files, in addition to the source code and configuration files, and the amount of the document can be used as a few: libbt-1.0 / readme: Readme file, described The function of libbt and generates a libbt library. Libbt-1.0 / DOCS / Protocol.txt: The description of the BitTorrent file transfer protocol. Libbt-1.0 / DOCS / Protocol-ext.txt: Additional instructions for BitTorrent file transfer protocol. Libbt-1.0 / man / btcheck.1: Example BTCheck's User Manual. Libbt-1.0 / man / btget.1: User Manual for the BTGet. Libbt-1.0 / man / btlist.1: User Manual for the BTLIST. Now, we may wish to make a hypothesis: If a programmer wants to write a BitTorrent program in Linux, he also went smoothly and downloaded the version 1.0 version of libbt, then, only the above help documentation, he can Was successfully developed? There are still many small-scale open source libraries like libbt, and they will provide programmers
What kind of technical documentation? The second example is not a development kit, but an open source software product that can be used directly. In order to prevent the programmers who read this article, I deliberately selected a software that most Java programmers are very familiar - the famous build tool ANT. I downloaded Ant 1.6.1 (http://ant.apache.org/). The ANT installation package contains a large number of electronic forms of documents, both of the readme files and versions, also have user manuals and common question and answers (FAQ), only the user manual occupies 22.9MB disk space, Ant document is complete and detailed. There is quite small in the open source project. In order to facilitate everyone to analyze the discussion, I translated Ant 1.6.1 user manual (Apache Ant User Manual) to translate the structure of the ANT 1.6.1 User Manual, and the list is below: Apache Ant User Manual Directory Overview Install Ant Get ANT System Requirements Install ANT Generate ANT Library Dependence Sexual platform related issues Using ANT Writing Simple BuildFile Project Target Task Property Corporate Properties BuildFile Sample Mark Filter Class Path Structure Command Line Parameters Reference Run Ant Command Booster Directory File Environment Variable Java System Properties Cygwin User OS / 2 Users pass Java runs Ant Ant Task Ant Task Overview Core Tasks .. Optional Tasks .. Concepts and Types. Editor / Development Environment Integrated Ant Development .. Ant API Reference .. License Agreement Feedback and Correction Author's list, this user manual is detailed? The user manual of Ant has considerable quality than the example of the previous Libbt. However, I still hope that everyone thinks about it. Is there anything that is not satisfactory in the user manual in Ant? If you want to increase the user manual of Ant, what should we start? 2 Before the external appearance case analysis, let's talk about a written statement. Many programmers have annoying writing documents, and thus annoying everything related to writing documents, such as hate diary (except blog), hate reading novels (except martial arts novels), hate Tattoo Dictionary (outside Kingsoft), etc., In the field of software development, the programmer with a low language level is very people. Although no one asks that the programmer must write four or six 骈 文, it is necessary to carry "Zhaoming Wen Di", but at least, programmers can't even create the wrong words in technical documents. For example, when I was college, I was surprised to find that the word "threshold" appeared in the graduation thesis of a brother of the computer. I don't solve it, and I have all across the authority tool book. By the face, it is not good to ask the brother to ask. After graduating, I listened many times to talk about the technical terminology of "threshold". Wanzhi helpless, I had to pull a good colleague asked. Who knows that colleague said that he said: "How do you learn in the university? Do you have to teach you in the classroom? For example, if the test score is more than 60 points, the calculation of 60 points or less Leg, then this 60 points are not a 'threshold'? "Until this, I suddenly realized that the so-called" threshold "is so stuff. In my experience, the value of the critical point is called "threshold" without calling "threshold", which can be used by the tool book - "Modern Chinese Specification Dictionary" said: "Threshold: 1 threshold. 2 limit; range.
"Obviously, those who open" threshold "and closing" threshold "are reading other words. But why will I miss" threshold "to" valve "? It is because they grow like twin brothers, or Because their five-strokes are quite approximate? In order to identify the truth, I will return to the school, spend a few days to listen to the computer system. The sky has a eye, I really let me meet: In the classroom of a well-known professor, I heard the professor to "read" the threshold (yù) value "valve (fá) value" (because of the well-known reasons, I didn't publicize the name of this professor. Now I understand, there is such a way to pass the horses, how can this world be less reading, write the programmer of the word? If you don't pay attention, everyone may not be aware, this "threshold" The mistake is so flood in the technical field, not only some of ordinary programmer "valve" comes to "valve", not knowing, many serious teaching materials, literature also righteously joined the line of other words. More funny things Also included:
A article named "Values Management" on the Sybase Chinese website, as well as a "threshold" and "threshold" in an article named "RMON and RMONII: Economically Valid Network Management" on the 3COM Two kinds of ways did not make each other, mutual nothing; in the full annotation of "Threshold" in Jinshan Word 2003, in addition to including several spelling "thresholds", there is actually quietly hidden "threshold" "In any case, this will remind us that" threshold "will remind us that although the programmer has been completely forgotten during the university, what kind of homework, but some basic knowledge about language and text, Do we still don't lose it. In addition, even when the primary school students encounter difficulties, we know to teach the dictionary. We can joke more than the primary school students! 3 Case Analysis is just like software to meet the needs of users, technical documents must also meet the user's reading needs. Judging with this standard, the two user manuals given in this article are not the best technical documentation. The first example - the deficiencies of theLibbt document are very obvious: Libbt's user manual is not a quality and bad problem, it does not provide the true user manual! From the assumption mentioned in the case, if a programmer wants to write a bittorrent program in Linux, he also found and downloaded the Libbt version 1.0. At this time, he most wants to get from libbt documents. What information? If I am the programmer, I want to know what is: What is Libbt? What functions do it achieve BitTorrent? Is it a dynamic library or static library? What are its interface or interface functions? How do we embed libbt in your code? How do I combine libbt with a graphical interface? It is very disappointing that there is no useful information in the libbt's release package in addition to the readmes (Readme). Libbt's Man Folder is a command line syntax description of the three sample programs developed by the libbt library, but I want to write a bittorrent program for a graphical interface, what is the use of these command line parameters? The DOCS folder seems to store the most valuable document, and only two files that can be found in the BitTorrent transport protocol - God, I downloaded libbt's purpose is to want to do not care about the BitTorrent transfer protocol details. Directly use a third party's development package to implement the BitTorrent program, now you let me read the documentation documentation of the Bittorrent transport protocol, is this not laughing at me? In fact, many programmers like to sell techniques like libbt when writing technical documents, regardless of the actual needs of end users. This phenomenon is particularly obvious in many software products released in the development package: programmers to develop documents are always habitually believed that the development package is to provide technical personnel, and users should understand the development kit. Details, even need to study code carefully, so the documents like the "Manual", "Getting Started" or "Guide" are not necessary. This idea is wrong, that is, because it ignores an important fact: the people who write a development package and those who use the development kit often have different interests, and their demand for technical documents is also very different. Take the libbt example, the person who writes libbt is concerned about the details of the BitTorrent protocol, and people who use libbt are concerned about the interface and usage of libbt.
Only the BitTorrent protocol will be provided to the user, and this approach is nothing difference with the purchase of the TV. I have also seen some types of libraries, when writing user manuals, just arrange all classes, attributes, and methods in alphabetical order, except for any information. To know, the programmer using the class library is most concerned about how to organize classes, properties, and methods in the class library into an organic overall to solve practical problems. For class libraries, the Dictionary reference is important, and the entry-based boot and help can be lacked. How do programmers understand the specific methods and steps based on class library programming? Of course, in the open source field, smart programmers can also get enough knowledge by reading the source code, but if the competitors' products are exhausted by the excellent document, they are uncomfortable, those products that are not perfect in the market can be in the market. Is it enough? In contrast, Ant's document is much better than libbt's documentation. The most obvious thing is that the structure of the Ant User's Manual strictly follows the ultimate agencies in a document compiling - I called this theorem as the "three-way theorem" compiled by the user manual, ie: Good user manual must include three major Part: Overview, Guide and Reference. Don't underestimate this simple "three-way theorem". Careful observation is not difficult to find, almost all excellent user manuals meet this level of demand. Take the Ant User Manual, the most beginning "Overview" is the most concerned about "Ant is" and "why you want to use Ant". Therefore, don't look at the space of the outlined part, it has achieved the role and status in the user manual. Imagine that users who have just purchased and downloading software have lack aware of the new software. If we can use one or two patriarchal texts to tell the user, the product can help them solve something, most users will Mo Boxing, jumps to try. It should be noted that in English User Manual, the chapter like "Introduction", "OverView", "What's ...", "Getting Started" can correspond to the summary part of the "three-way theory theorem". The guidelines in the "Three Test Instructions" can generally correspond to the "Tutorial", "Guide", "MANUAL", "How to ...", "Using ..." in the English User Manual, sometimes including " Getting start "or" step by step "and so on. Simply put, the guide is how to teach users how to use software products, how to complete specific tasks, which solves "how to do something". In the Ant User Manual, "Install Ant", "Use Ant", "Run Ant" three chapters of the guide belong to the nature of the guide. Through the reading of these three chapters, a person who has never used Ant can be installed and running Ant, and manages a simple project. The reference refers to the "three paragraph theory theorem" is any excellent user
The manual should be fully complete, organizational, and easy to inquire, which is the same as any excellent technical books should provide reference or cross-index after book. The corresponding sections in the English User Manual include "Reference", "Glossary", "INDEX", and more, and what they want to solve "How to quickly find specific information". In the Ant User Manual, several chapters such as "Ant Tasks", "Concepts and Types", "ANT API Reference" can play a reference. For example, when I saw a "cvstagdiff" task I have never used by others, I can quickly find the list of task names in alphabetical order through the "Ant Task" chapter. "CVSTAGDIFF" and understand the specific use of this task. In addition to the software products of Ant, most of the software for ordinary consumers need to provide adequate references in the user manual. For example, there is no shortcut key, toolbar buttons, and menu items in its print manual or online help. In the end, most of the ultimate users must call it. Why is a good user manual necessary to meet the requirements of the "three-way theory theorem"? This is because the user manual should meet the needs of different types of users as much as possible, and the outlines in the "three-section theory theory" is exactly caused by factors, complement each other, and build a step-by-step document system: for software products Nothing users first understand the basic characteristics of the product with an overview; then, the user can learn the use of the product by shallow to deeply in the guide; Next, once the user encounters difficulties, products References can be used to play a question. In the user manual of Most products in Microsoft, we can find document structures that meet the "three-section theory theorem". Taking the MSDN document that we are most familiar with the program (we can treat MSDN documents as a Microsoft's development tool and the user manual for the development package) as an example, the MSDN document is very normative in structure and content, in its directory structure Almost every technical unit consists of "Overview", "Tutorial", "Reference" or similar document elements, and the entire MSDN document library organizes orderly and reasonable. It should be said that many experiences accumulated in the technical document compilation of Microsoft companies are worth learning and drawing. Now, we already know that the Ant User Manual given in the case is structured in accordance with the requirements of the "three-section theory", and the quality of the Quality of Libbt has a noffer. But why should I say that Ant user manual is not the best technical documentation? If you use a stricter standard to measure the quality of the ANT user manual, we still find many of them. In fact, it is not much different from the method of assessing a user manual and assessing a set of software. Recall that when we examine the quality of a software product, what is the most critical standard? That's right, whether the product is in line with the needs of users. Programmers who are familiar with object-oriented software engineering and use cases will think that we can evaluate software products in a use case realization or per-casement (Scenario) based on the needs of the demand phase. To determine the degree of anastomosis between software products and user needs, and integrate the quality of the software products. So, can we evaluate technical documents, especially the quality of the user manual, by using the use case analysis and the method of verification. In the previous analysis, we have unconsciously use the method of use case analysis.
For example, the three elements in the "three-way theory" correspond to three user needs - to understand product profiles, familiar with how to use methods and troubleshoot problems, are they not the three main use cases when reading user manuals? According to our analysis, Ant User Manual can basically solve these three main use cases involved, but this "solve" is the most complete and efficient solution? Perhaps we also need to design a deeper use case to find the answer to this problem. For example, the "use of Ant" in the Ant User Manual is a guide nature, according to the requirements of the "three-way theory", the role of this chapter is to guide the user to learn Ant. So, is the "use of Ant" to cover most of the common usage of Ant? the answer is negative. Chapter of "Using Ant" only introduces the basic usage of Ant, and gives a simplest buildfile sample, which can tell users how to use Ant to complete the most basic software generation task, it cannot provide more guided information . For example, the buildfile sample given in the "Using Ant" contains a task called "Clean", but the document does not expand, how similar "clean" cleaning task should be implemented in Ant, some of which may Which Ant tasks, properties, and types involved - this description, ANT's user manual cannot achieve this specific deep use case. In addition, for "How to integrate different Ant projects", "How to use ANT Management Folders and File Structure", "How to Record and Display Error Messages", "How to Access the CVS Source Library in Ant", "How to Compress and Urink Archive Document ", etc., there is no more common problem during the use of Ant, and" using Ant "has not given a detailed introduction. Some said that programmers can find relevant content from the "Ant Task" chapter in the Ant User's Manual, and some say that the common question and answer (FAQ) provided by Ant also contains similar information. But don't forget, different types of documents shoulders are different, and suitable use cases are also different. Chapter 1 with Ant is the guide document, which is suitable for "learning ANT usage", and "Ant Task" chapter and common question and answer (FAQ) belongs to the reference nature, its structure and content are only available The main use case of "Quickly check" when you encounter problems ". In other words, the Guide in the ANT User Manual is lacking on the implementation of deep use cases such as "learning through Ant integration different items", and does not fully assume the responsibility of booting and professor. Those users who can't master enough skills in the guidelines are only to the reference part, but they can rely on reference or claims to learn software usage is like learning English in English. It is a matter of hard work. That is to say, in a similar case, we should try to complete the guide document to achieve all deep use cases, rather than kicking innocent users to other document types like kicking the ball. Regarding the guide section of the user manual, most of the relevant chapters in Microsoft MSDN documents provide us with the best examples. For example, in the "use .NET Framework program" 2, it contains "using ADO.NET
Access data "," Use the .NET remote mechanism to access objects in other applications "," Access Internet ", 30 topics, etc., almost all common tasks in .NET development. Obviously, users can tutorial in these topic Under the guidance, step-by-step development methods, understand the specific steps of .NET programming. Most importantly, almost all guide contents in the MSDN document are organized in the subject, and each topic is trying to solve one. User's most concerned issue, or trying to guide users to complete a specific task. From this perspective, we can also refer to MSDN's guide documents as "topic documents" or "mission-oriented documents". Ant User Manual The reference part of the in-reference part is also kind. The most depressed is that Ant User Manual In "Ant Task" chapter, the Ant task is listed in "core tasks" and "optional tasks" two categories, "concepts and Type Chapter There is also a similar approach. Although the entries under each category are arranged in alphabetical order, the Ant User Manual is not given a complete list of all Ant tasks, attributes, and types. With a simple use case You can easily discover the "JJTree" tab that I have never seen before I have written in the buildfile written in others, and I want to find its meaning in the user manual, but how do I know this "jjtree" Is an Ant task, or an ant type? Even if I can determine "jjtree" is an Ant task, then I am looking for "Core Task", or to "Optional Task"? Ant Document Lack of Unity The distinct of the index clearly affects the user's query efficiency; in order to improve efficiency, I often use GREP to retrieve ANT documentation - don't underestimate this problem, maybe, some differences in search efficiency is enough to prompt your potential users to choose competition The opponent's product! In terms of reference and indexing, Microsoft's MSDN documentation is equally impeccable. In addition to organize and complete "Reference", "Glossary", MSDN provides us with a unified index (INDEX) , Find (Search) and favorite (Favorites) function. With these functions, the programmer can freely shuttle in the huge MSDN information ocean. In addition, in each document page of MSDN, related The theme (Related Topics), see (see also), hyperlink, etc. The cross-index mechanism is not uncommon. Undoubtedly, in terms of the improvement and ease of use of document retrieval function, Microsoft has long been leading, like Ant. The project is difficult to see the back. The programmer for the development of electronic document technology may have already noticed, Microsoft Excellent performance in technical documentation and Microsoft accumulates in the relevant technical field. Only in the electronic version of the help file format, Microsoft has launched three versions of * .hlp, *. Chm and * .hxs. It is said that in the future LONGHORN operating system, the performance of the help file will have a quality leap 3. Of course, technology does not decide everything. Like Sun's Javahelp (http://java.sun.com/products/javahelp/), Oracle's Help for Java (http://otn.oracle.com/tech/java/help/) and other cross-platform electronic documents The build tool can also provide a rich features, but the excellent documentation issued by these tools is still less. Perhaps, Microsoft's success more in the document area is from the company's attention to user needs, emphasizing the easy-to-use sexual ideas of products.
4 Supplementary Note Since the "object-oriented" is widely circulated in the industry, the programmer seems to have a unique closure of "facing.", "Facing", "facing the contract", " "," Used "," Mode "," Architecture "," Components ", etc. Termatic, and unpacking. Here, I also rushed back to fashion, using "facing.", Simply lists the types of commonly used technical documentation: .. Oriental documents: Writing only a few experts can understand the documentation. This method is only applicable to a small number of scientific research, which is never suitable for documents such as the user manual and the end user service. .. Document for idiot: Overview and guidelines in most user manuals should be intercounted documents, only the ease of use of documents can achieve the best embodiment. .. Conceptual document: The outline documentation in the previous "three-section theory theorem" in the previous "three kinds of theory", and the common self-name files belong to this type. .. Document for tasks: The highest performance form of the guide document, focusing on the implementation of the task, rather than specific technical details. The more common "How to ..." chapter in MSDN is an excellent example of this type of document. .. retrieved documents: Reference, index, gloss, and all electronic forms of documents can be used for information retrieval, but different compilation methods have great impact on search efficiency - this requires document editor to have more information retrieval Knowledge and better document compilation tools. .. Document-Oriented Document - FAQ is a common, flexible, effective, and a relatively good reference, but most FAQ is a loose, lack of effective index and classification. system. .. error-oriented document - mainly includes troubleshooting, error list, fault check, and other documents. .. Legal document - End User License Agreement (EULA), Software Licensing Method (License) or other legal documents is often an important part of software products. .. Historic document - includes version history (Timeline), etc. ... 5 summarize .. Write document also has certain regularities. The programmer must not "fear" to write a document; .. Technical documentation or service for the developer, or serve the document The need is a shortcut to write a document. 1 Microsoft. MSF Team Model. Http://www.microsoft.com/msf/, 2003 2 Microsoft. Programming with the .net framework. Http://msdn.microsoft.com/library/en-us/cpguide/html /cpconProgrammingWithNETFramework.asp, 2004 ③ Microsoft. Introducing Windows "Longhorn" Help. http://msdn.microsoft.com/library/en-us/htmlhelp/html/hwms cIntroducingWindowsLonghornHelp.asp, 2004
