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

[Clark B. Wierda]

Previous attempt to devel at ntpsec.org bounced, but everything looks good now.

I apologize to those that already received this.

Clark B. Wierda

---------- Forwarded message ----------
From: Clark B. Wierda <cbwierda at gmail.com>
Date: Sun, May 22, 2016 at 2:10 PM
Subject: Re: [gpsd-dev] Draft Stratum 1 Microserver HOWTO is up
To: gpsd-dev at nongnu.org, devel at ntpsec.org
Cc: "Eric S. Raymond" <esr at thyrsus.com>


Just a few general thoughts:

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.

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.

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.

Likewise, I think we should like the scope in the primary sections to the
Raspberry Pi.  There are at least 5 variants there (at least 2 of which
will not accept the GPS HAT).  [I'd actually be tempted to write to the RPi
2B as that is likely to be the most common while avoiding the issues with
the RPi 3B.  The special case would be handled as noted above with special
section on the differenecs.]  There are many documents on the 'Net that
reference another document as a baseline and only document the changes.
The Raspberry Pi is likely to remain the majority player in this space for
the foreseeable future.  Some of the other devices in this space are going
to be work-alike or work-similar.  Most users who are going to be trying
something like an ODroid, or Banana, are likely to be able to handle the
needed adjustments themselves.  Something further afield, like the
Beaglebone, will be different enough to add significantly to the complexity
in handling.

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'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 know this is late in the process for this kind of input, but I hope this
is still useful in some way.

Regards,
Clark B. Wierda
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ntpsec.org/pipermail/devel/attachments/20160522/9fa70d75/attachment.html>