📄 00000030.htm
字号:
<HTML><HEAD> <TITLE>BBS水木清华站∶精华区</TITLE></HEAD><BODY><CENTER><H1>BBS水木清华站∶精华区</H1></CENTER>发信人: Quixon (Now or Never), 信区: Linux <BR>标 题: The Document is the Program <BR>发信站: BBS 水木清华站 (Sat Jan 1 22:04:02 2000) <BR> <BR>这是我在www.freshmeat.net上看到的一篇文章, 很有道理. <BR> <BR> Over the years, desktop computer users have thrown up a number of <BR> straw men to explain why they can't use Free operating systems. The <BR> community has shot them down one by one, from "It doesn't support <BR> my hardware" to "There's no business software available", but there's <BR> still one complaint that too often goes unanswered: "I can't make heads <BR> or tails of this manual!" In today's editorial, Hairy Larry discusses the <BR> need for documentation and the three types of documents he thinks are <BR> essential to any program. <BR> <BR> <BR> Copyright notice: All reader-written material on freshmeat is the property and responsibility of <BR> its author; for reprint rights, please contact the author directly. <BR> <BR> <BR> Just how important is documentation to the success of your program? <BR> Without a doubt, the documents are the most important pieces of your <BR> code. <BR> <BR> Specifications Documents <BR> <BR> Before you write a line of code, you should have at least a preliminary <BR> version of your specifications document. This does not mean that you <BR> shouldn't write toy programs as feasibility studies. (It's nice to know <BR> that something is possible before you commit to a lot of work.) It does <BR> mean that before you start on your .001 Alpha version, you should have <BR> a pretty good idea of where you are going. <BR> <BR> And here's the reason why: Algorithms + Data Structures = Programs. <BR> Or, as I have heard it said, the database is the program. I really don't <BR> know of any substantial programming project that doesn't rely on data. <BR> <BR> Getting your data structure right is hard. Mistakes in your data <BR> structure lead to massive rewrites. You have to put a lot of thought into <BR> how your database will work and how your code can access it. How can <BR> you even think about this until you have a pretty good idea about where <BR> you are going? <BR> <BR> Of course your specifications document will change. It's a good idea to <BR> add version control to your specs from the outset. I'm sure you plan on <BR> enhancing your program by adding new features and bringing out new <BR> versions. These features will have to be specified, so track the changes <BR> in your specs just like you track the changes in your code. <BR> <BR> Programmer Documents <BR> <BR> I learned that even on projects on which I was the only programmer, I <BR> would often come back a month later (or the next day) and wonder <BR> "Just what was I doing there?" Now I'm assuming that if you are <BR> working on an open source project you are hoping that other <BR> programmers might get involved. How can you possibly expect them to <BR> figure out "What is he doing there?" <BR> <BR> Each piece of source code should be documented at the top. Describe <BR> its overall function, what modules call it, and what modules it calls. I <BR> find it helpful to write this before I start coding to focus my attention on <BR> the problem at hand. In the source, each block of code should be <BR> documented with inline comments. What does this variable do? What <BR> algorithm am I using here? Why does this piece of code even exist? <BR> These questions and more should all be answered by inline comments. <BR> <BR> You also need a single large document for the entire project. This <BR> document should describe the data structure and the overall structure of <BR> the program. Each module and its function should be included. You <BR> also need a list of all the documents for the project. Include a way to get <BR> in touch with you. Just because you understand what you are trying to <BR> say doesn't mean that the programmers reading the document will. <BR> Make it easy for them to ask questions and include your clarifications in <BR> the document. <BR> <BR> By providing good programmer documents, you make it possible (not <BR> easy, just possible) for other programmers to come on board and help <BR> you with your project. <BR> <BR> End User Document <BR> <BR> The end user document (AKA the Manual) is the most important <BR> single piece of your entire project. It's more important than the data <BR> structure. It's more important than the code. It's more important than <BR> the documents described above. It is also, unfortunately, the most <BR> neglected. <BR> <BR> Write your manual in plain, simple English. (French, German, <BR> Japanese, etc.) Use no jargon. Assume nothing. Describe the purpose <BR> of the program. List the major areas of functionality. Include <BR> step-by-step instructions on how to get from point A to point B. <BR> <BR> How can you possibly expect the user without a manual to know that <BR> he has to click on the frammistran before going to the screen where he <BR> enters the stuff describing the fujitron? It may be obvious to you, but <BR> it's certainly not obvious to me. <BR> <BR> I know most users won't read the manual. Instead of shouting "RTFM, <BR> RTFM", include context-sensitive help. Online help is the other side of <BR> the end user documents. Let your user hit the F1 key and view the <BR> portion of the manual appropriate to the task at hand. This is certainly <BR> easier than digging out a book or searching through a text file. <BR> <BR> Quality end user documentation requires both a single large manual <BR> with all the documentation that a user can read or refer to and <BR> context-sensitive help at the touch of the finger when he needs it. <BR> <BR> Closing <BR> <BR> When a student in the Department of Math and Physics, I remember <BR> well the gearheads sneering at the English Majors who were having so <BR> much trouble with their required math courses. At the same time, there <BR> were no required writing courses for the Computer Science degree <BR> beyond Freshman English. <BR> <BR> After I graduated, I realized that the most important skill leading to <BR> advancement was not the ability to do calculus. It was not being able to <BR> churn out tons of hot shot code. It was not the ability to design elegant <BR> data schema. <BR> <BR> The most important skill is the ability to write well and communicate. It <BR> doesn't matter how good you are and how hard you work. If you can't <BR> communicate what you are doing and why you are doing it, you will be <BR> passed over for advancement. The reason for this is simple. The <BR> managers making the promotion decisions are not computer scientists; <BR> they are managers. They can't read code. They read English. If you <BR> can't write English, you just remain a cog in the machine. <BR> <BR> Applying this to the world of open source software, it doesn't matter <BR> how good your code is. Most of your users will never read your code. <BR> They will read your documents. If your documents are well written, the <BR> users will find it easy to run your program. If not (or worse, if there's no <BR> documentation at all), potential users will hit a stumbling block and <BR> falter. They will then decide that the program is hard to use and look for <BR> another one. After all, they haven't made a major financial investment, <BR> so it's easy for them to walk away and try something else. <BR> <BR>-- <BR>※ 来源:·BBS 水木清华站 smth.org·[FROM: 166.111.161.104] <BR><CENTER><H1>BBS水木清华站∶精华区</H1></CENTER></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -