BBS水木清华站∶精华区

发信人: Quixon (Now or Never), 信区: Linux
标  题: The Document is the Program
发信站: BBS 水木清华站 (Sat Jan  1 22:04:02 2000)

这是我在www.freshmeat.net上看到的一篇文章, 很有道理.

  Over the years, desktop computer users have thrown up a number of
  straw men to explain why they can't use Free operating systems. The
  community has shot them down one by one, from "It doesn't support
  my hardware" to "There's no business software available", but there's
  still one complaint that too often goes unanswered: "I can't make heads
  or tails of this manual!" In today's editorial, Hairy Larry discusses the
  need for documentation and the three types of documents he thinks are
  essential to any program.

  Copyright notice: All reader-written material on freshmeat is the property and responsibility of
          its author; for reprint rights, please contact the author directly.

  Just how important is documentation to the success of your program?
  Without a doubt, the documents are the most important pieces of your
  code.

  Specifications Documents

  Before you write a line of code, you should have at least a preliminary
  version of your specifications document. This does not mean that you
  shouldn't write toy programs as feasibility studies. (It's nice to know
  that something is possible before you commit to a lot of work.) It does
  mean that before you start on your .001 Alpha version, you should have
  a pretty good idea of where you are going.

  And here's the reason why: Algorithms + Data Structures = Programs.
  Or, as I have heard it said, the database is the program. I really don't
  know of any substantial programming project that doesn't rely on data.

  Getting your data structure right is hard. Mistakes in your data
  structure lead to massive rewrites. You have to put a lot of thought into
  how your database will work and how your code can access it. How can
  you even think about this until you have a pretty good idea about where
  you are going?

  Of course your specifications document will change. It's a good idea to
  add version control to your specs from the outset. I'm sure you plan on
  enhancing your program by adding new features and bringing out new
  versions. These features will have to be specified, so track the changes
  in your specs just like you track the changes in your code.

  Programmer Documents

  I learned that even on projects on which I was the only programmer, I
  would often come back a month later (or the next day) and wonder
  "Just what was I doing there?" Now I'm assuming that if you are
  working on an open source project you are hoping that other
  programmers might get involved. How can you possibly expect them to
  figure out "What is he doing there?"

  Each piece of source code should be documented at the top. Describe
  its overall function, what modules call it, and what modules it calls. I
  find it helpful to write this before I start coding to focus my attention on
  the problem at hand. In the source, each block of code should be
  documented with inline comments. What does this variable do? What
  algorithm am I using here? Why does this piece of code even exist?
  These questions and more should all be answered by inline comments.

  You also need a single large document for the entire project. This
  document should describe the data structure and the overall structure of
  the program. Each module and its function should be included. You
  also need a list of all the documents for the project. Include a way to get
  in touch with you. Just because you understand what you are trying to
  say doesn't mean that the programmers reading the document will.
  Make it easy for them to ask questions and include your clarifications in
  the document.

  By providing good programmer documents, you make it possible (not
  easy, just possible) for other programmers to come on board and help
  you with your project.

  End User Document

  The end user document (AKA the Manual) is the most important
  single piece of your entire project. It's more important than the data
  structure. It's more important than the code. It's more important than
  the documents described above. It is also, unfortunately, the most
  neglected.

  Write your manual in plain, simple English. (French, German,
  Japanese, etc.) Use no jargon. Assume nothing. Describe the purpose
  of the program. List the major areas of functionality. Include
  step-by-step instructions on how to get from point A to point B.

  How can you possibly expect the user without a manual to know that
  he has to click on the frammistran before going to the screen where he
  enters the stuff describing the fujitron? It may be obvious to you, but
  it's certainly not obvious to me.

  I know most users won't read the manual. Instead of shouting "RTFM,
  RTFM", include context-sensitive help. Online help is the other side of
  the end user documents. Let your user hit the F1 key and view the
  portion of the manual appropriate to the task at hand. This is certainly
  easier than digging out a book or searching through a text file.

  Quality end user documentation requires both a single large manual
  with all the documentation that a user can read or refer to and
  context-sensitive help at the touch of the finger when he needs it.

  Closing

  When a student in the Department of Math and Physics, I remember
  well the gearheads sneering at the English Majors who were having so
  much trouble with their required math courses. At the same time, there
  were no required writing courses for the Computer Science degree
  beyond Freshman English.

  After I graduated, I realized that the most important skill leading to
  advancement was not the ability to do calculus. It was not being able to
  churn out tons of hot shot code. It was not the ability to design elegant
  data schema.

  The most important skill is the ability to write well and communicate. It
  doesn't matter how good you are and how hard you work. If you can't
  communicate what you are doing and why you are doing it, you will be
  passed over for advancement. The reason for this is simple. The
  managers making the promotion decisions are not computer scientists;
  they are managers. They can't read code. They read English. If you
  can't write English, you just remain a cog in the machine.

  Applying this to the world of open source software, it doesn't matter
  how good your code is. Most of your users will never read your code.
  They will read your documents. If your documents are well written, the
  users will find it easy to run your program. If not (or worse, if there's no
  documentation at all), potential users will hit a stumbling block and
  falter. They will then decide that the program is hard to use and look for
  another one. After all, they haven't made a major financial investment,
  so it's easy for them to walk away and try something else.

--
※ 来源:·BBS 水木清华站 smth.org·[FROM: 166.111.161.104]