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

David L. Mills mills at udel.edu
Sun Oct 5 03:05:51 UTC 2003


Harlan,

Yes, I do have some thoughts. It should be possible for a greenie to
bring up a bare-simple NTP installation without having to navigate
anything except what comes with the distribution. There are lots of
other packages that conform to this model, including openssl, openssh,
amanda, gcc and many others I have had to climb over myself recently.
These all have instant ignition READMEs, reference pages and web
pointers, which normally are all that folks need.

There is definitely an image problem in the NTP documentation area right
now and not a little bit of religious ferver to promote the twichy as AI
newbie helper. I have no problem with that as long as more conventional
alternatives are available, includint the reference pages, README files,
faq and newsgroup. Anybody can see from the current distribution the
cultural divide between manpagers and webpagers. There's several README
text files largely duplicated in the HTML pages. Now that everybody has
a browser I see no need for the READNE text files other than pointers to
the HTML pages, especially of HTML->text utilities are available. It
could be well the case that some HTML pages are a mouthful and probably
should be split, but there are tutorial and quickstart pages.

Over the years there has been an ongoing transfer of executive
summaries, briefings and technical information other than for the
implementation from the distribution documentation to the NTP project
page, which reduces distribution bloat and makes it much easier for me
to update in only one place. The distribution documentation is a special
case, as dim eyesight requires me to maintain it offline with
eye-friendly devices. These pages are intended as a definitive reference
manual and not a greenie tutorial.

There are two missing areas that are in some process or other of being
addressed lately. One is a touchy-feely O'Reillyian tutorial to explain
what ths stuff does, how to build it, how to get it going and how to fix
what breaks. I understand a tutorial is already in the works and assume
it will be a flat document appropriate to accompany the faq. There is a
stunning collection of good NTP tutorials in the Sun Knowledge Base and
elsewhere just ripe for links.

I see the twichy as an interactive learning tool and solutions manual,
which can be very valuable. However, the lessons learned there should
not stay there indefinately and should wind up in flat documents. In
other words, the twichy should be very good at capturing and sifting
useful lore, but should not be the exclusive path to solutions,
interactive or not.

Dave



Harlan Stenn wrote:
> 
> We agree on the goals...
> 
> My belief is that the existing GettingStarted page will need to grow and
> evolve beyond the point where it can be useful (or maintained) as a single
> document, but that's just my opinion and I'm happy to be shown otherwise.
> 
> And I also agree that the pages under "General Options" need to be easier
> to navigate.  Maybe Steve has some ideas on how that can be improved.
> 
> I also expect that somebody else may have a different idea of how to help
> folks get started, and we should have an easy way to allow this.
> 
> Anyway, I'm inclined to see the existing GettingStarted page moved to a
> new name (maybe QuickStart?), and then have the new GettingStarted page
> contain a pointer to that page and also the existing stuff under the
> "General Options".
> 
> That way we can use a single pointer to the GettingStarted page and
> people will have an easy choice of which style of info they would like
> to use.
> 
> Thoughts?
> 
> H
> --
> In article <87lls036yl.fsf at netnews.comcast.net>,
> Dale Worley  <worley at dragon.ariadne.com> wrote:
> 
> >IMHO, the monolithic structure is necessary -- The point is to get the
> >user from zero to "ntp synced" as easily as possible.  An information
> >source that needs to be navigated works against usability.  The best
> >is a single document that can be read and acted upon in linear order.
> >Of course, that does increase the effort needed to maintain it, since
> >you can't just edit a sentence here or there without considering its
> >impact on the rest of the document.  But it seems to me that getting
> >one's ntpd configuration started is the single largest barrier to NTP
> >adoption.



More information about the questions mailing list