[ntp:questions] Re: Latest changes to TWiki GettingStarted

Dale Worley 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.

Dale



More information about the questions mailing list