标 题: 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]
Posts
