[ntp:questions] Re: Latest changes to TWiki GettingStarted
brad.knowles at skynet.be
Sun Oct 5 15:34:40 UTC 2003
At 3:05 AM +0000 2003/10/05, David L. Mills wrote:
> 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.
As a goal, I agree.
> 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 don't see this as an "image problem". I see this as a very real problem.
I look at the official documentation and I see nothing in there
that appears to be suitable for newbies. Moreover, I submit that
there almost certainly isn't anyone on this newsgroup/mailing list
who would be qualified to know what is truly suitable for newbies --
by definition, once you've made it onto this newsgroup/mailing list,
you've already learned quite a lot about NTP and where NTP-related
discussions take place, and that has to be the single biggest step
for newbies to take.
Instead, we offer the twiki as a place where newbies can go and
help us to understand where they need the most help.
Moreover, since the entire community can directly contribute to
the twiki, we can take advantage of their knowledge and perspective
without having to bottleneck on someone else to take their
contributions and re-work them into a format that would be suitable
for incorporation into the other official sources of documentation.
If you always bottleneck on the same resources, no matter how
good those resources may be, you're guaranteed to have problems. The
fewer bottlenecks through which everything must be funneled, the more
likely you are to have more frequent failures and the more likely
they are to be catastrophic in nature.
> 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.
The entire world is not comprised of the world-wide web. There
are plenty of us who do not have access to web browsers at all times,
and certainly not at some of the most important times -- such as when
a server is being installed under a serious time crunch.
Plain text files are the lowest common denominator, and if we
don't provide all documentation in plain text files (with other
formats optionally available), then we are not serving the community.
Otherwise, we might as well start shipping exclusively Microsoft
Word format documentation, because "everybody knows that everybody
has a PC".
> 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 think we can fix this problem, or at least be part of the solution.
I will talk to some people.
> I understand a tutorial is already in the works and assume
> it will be a flat document appropriate to accompany the faq.
Can you provide more information on this?
> There is a
> stunning collection of good NTP tutorials in the Sun Knowledge Base and
> elsewhere just ripe for links.
I agree that we need to provide a more complete set of links to
other documentation elsewhere. But there's also a whole boatload of
really bad crap out there, and we should also work to try to get that
stuff corrected or removed.
> 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.
As I see it, the twiki should be in a pretty constant state of
flux, always being improved or tweaked.
> 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.
We could periodically capture this information into a static
file, but the thing that makes the twiki most useful is the very
dynamic nature of the beast. Without that, we might as well just
have another FAQ maintainer.
Brad Knowles, <brad.knowles at skynet.be>
"They that can give up essential liberty to obtain a little temporary
safety deserve neither liberty nor safety."
-Benjamin Franklin, Historical Review of Pennsylvania.
GCS/IT d+(-) s:+(++)>: a C++(+++)$ UMBSHI++++$ P+>++ L+ !E-(---) W+++(--) N+
!w--- O- M++ V PS++(+++) PE- Y+(++) PGP>+++ t+(+++) 5++(+++) X++(+++) R+(+++)
tv+(+++) b+(++++) DI+(++++) D+(++) G+(++++) e++>++++ h--- r---(+++)* z(+++)
More information about the questions