[ntp:questions] Re: Latest changes to TWiki GettingStarted
worley at dragon.ariadne.com
Sun Oct 5 12:17:20 UTC 2003
hmurray at suespammers.org (Hal Murray) writes:
> It's nice to have a single document that tells you everything you
> need to know. The flip side is that if it has too much, then
> you have troubles finding the important stuff.
Yes, that's true. OTOH, if the quick-start "has too much", then the
software is too complicated for ordinary people to use!
> I think there are two kinds of info you need when getting started.
> One is the overview, the general concepts. I can usually read that
> sort of thing once and not need to go back very often. The other
> kind of document is the details.
> Can the overview be split out? Would that help? (I'm assuming there
> would be a sentence at the top saying "Go read this".)
I think the way to structure it is to have the quick-start contain an
overview, but only the most minimal one that gets the job done. It
should have pointers to fuller overviews, but the quick-start should
need only a few sentences. But without an overview describing what
NTP does, the document isn't self-contained.
In regard to structure, I'm trying to hold to the principle of a
single, linear document so as to minimize navigation problems. (That
structure can also be turned into a text file, a man page, or a
printed page, so we avoid making a commitment now as to *how* the
quick-start is to be distributed.)
> How different are various OSs or environments? Would it make sense
> to have separate documents for Windows, BSD*, Red-Hat, ???
It would increase the bulk and complexity, I think. More importantly,
length per se isn't such a problem, since the reader can easily skip
over the irrelevant sections if they're well-marked.
More information about the questions