Fwd: [gpsd-dev] Draft Stratum 1 Microserver HOWTO is up

[Eric S. Raymond]

Clark B. Wierda <cbwierda at gmail.com>:
> It might be easier to follow if the "clockmaker" sequence is presented
> separately from the "manual" sequence.  Likely, this would be different
> parts of the same document.

I considered doing it that way.  I didn't because I think having the manual
intructions and some theory of operation in-line will educate the reader
better for the case where something unexpected happens, not just at build
time but in operation.

> Any discussion of fudge factors beyond any defaults in the code (if PPS is
> reliable, they are not needed) and performance tuning is applicable to any
> installation and should be a separate document.  The Timeservice document
> related to GPSD already exists and discusses many of these items.

If you'd like to read the GPSD Time Service HOWTO and systematically suggest
where and how we should link to it. I'd like to see that. I'm probably
too close to both documents to have the right perspective.

> The main sequences noted above should document the "happy path".  Handling
> the problem should go to a Troubleshooting section with more detailed
> information.  This will reduce the opportunity to confuse the naive user
> that is the target of this document.

See above...and be aware that I hate, hate, HATE "happy path"
checklists with a burning passion, and wouldn't write one unless at
gunpoint. I've ground my teeth as a victim of that kind of lazy,
thoughtless crap too often to inflict it on anyone else.

The problem is that they may get you from point A to point B if
everything goes exactlt right, but they don't convey generative
knowledge or coping skills if something goes wrong.  They're the
subtlest way to write bad documentation, and enrage me more than you
can probably understand.

> Likewise, I think we should like the scope in the primary sections to the
> Raspberry Pi.

I am *explicitly* not going to do that.  For several reasons, one of
which is our developing relationship with the BeagleBone folks.

> Finding the IP of the Pi would be one of those things that could go in a
> separate section if it doesn't "just work".  Just adding a keyboard and
> monitor long enough to find the address is likely to work for most people.
> Much beyond that is going to be risking confusion to the target audience.

I wouldn't mind seeing that as an "Advanced Topics" section, but I
can't justify taking the time to write it myself fr reasons you've
pointed out.  I'd take a patch...
 
> I'm reminded of the NTPsec motto and I think we should apply that here.
> The main sequence should be as simple as possible.  I think the sections
> could be something like Introduction, Scripted/Automated/clockmaker,
> Manual, Troubleshooting, Special Cases, References.

I think it *is* as simple as possible given my tutorial goals.  Advocating a
different goal is not a simplicity argument.

> I know this is late in the process for this kind of input, but I hope this
> is still useful in some way.

It will be if I can get you to actually deliver on a useful set of links
to the GPSD Time Service HOWTO. :-)

I can't do everything, man.  I don't have time.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>