Hi,
My own real-life work load has grown to amazing proportions, so I've just
been able to take a cursory look at the docs in 1.94b3. I have a couple
of suggestions (and, yes, I'm willing to actually do the work...):
* The official source format for all documentation should be HTML. All
documents should be in a single set of clearly interlinked pages. We can
include a plaintext version of everything by piping it all through lynx
in dump mode, and stored in a subdir labelled something like
'plaintext'. (I still think, though, that we
should maintain some kind of man format pages, which would be included,
but should still be auto-generated from the HTML source.)
* We should entirely separate out documentation for the various
versions. 1.94 should only be distributed with information that's
relevant to version 19.4. When I installed MD 1.93 for the first time,
over a year ago, I found the documents extremely disconcerting and very
confusing. They try to do too much. There were examples for various
versions of MD all mingled together. We can't have all of that info
together. A clearly labelled sub-section of the 1.94 docs can deal with
upgrading from various previous versions, each with their own sub-sub
section. (For example, 1.92->1.94. 1.93->1.94.)
Comments?
- Robb
-
Robb Shecter PGP Fingerprint:
University of Maryland, European Division 5F 70 B1 A7 B9 F9 42 67
Information Systems and Administrative Computing 11 27 47 EE 35 80 04 AA
Follow-Ups:
|
|
