Stratum 1 microserver HOWTO

[Eric S. Raymond]

Paul Theodoropoulos via devel <devel at ntpsec.org>:
> On 7/30/18 20:46, Gary E. Miller via devel wrote:
> > We found a lot of people that wanted a cheap stratum 1 had not clue
> > how to get a RasPi to work.  Thus the completer instructions.
> ...
> > Please do.  Especialy with a fresh eye.  We dont know what newbies
> > don't know.
> ...
> > I like to think of that as the engineering and software worlds, but
> > some people that need a Stratum-1 are not of our world(s).
> So, I've spent a pretty fair bit of time poring over the stratum one howto
> off and on over the last year, have pushed a lot of fixes, changes,
> suggestions to ESR who kindly reviews and publishes as time permits.

You big polishing patchset has just been integrated.  It was excellent work;
thanks.

> Overall though, the howto is in need of TLC. As it stands, it's in a sort of
> a stream-of-consciousness form - understandably so, writing a very thorough
> howto as you go along the process yourself winds up that way, been down that
> road many times.

The reason it's that way is because I hate with a bitter and
incandescent passion the kind of HOWTO that baldly lays out a series
of steps without also teaching the background needed to troubleshoot
when a step does not lead to the expected result.

Such HOWTOs leave the reader totally at sea in case of failure, and
tend to age rapidly and badly.  I will never write one like this.

The only way I know to prevent this failure mode is to write in a way
that conveys both instructions and *expertise* - teaches not just what
the steps are but *why* they are, in effect pulling the reader partway
inside the mind of the author.

> 1. It needs a linked table of contents at the top. It's really easy to lose
> your way, because the content digresses to address many variances in the
> build process. Maybe that's not a 'big' thing, but more of an organizational
> nicenety.

Easily enough accomplished with :toc: in the options block.  I think this
is a good idea, and have already made the change.

> 2. I think the whole document needs branching - breaking it into multiple
> sub-pages, with the ability to self-direct to the next appropriate section.
> 
> For example, I think it should have a specific Hardware page/subpages, for
> each of our 'known' GPS boards, and SBC's. Dealing with pinouts, traces, etc
> etc etc.  Sort out the physical aspects into their own 'realm'  within the
> overall schema.

Branching that way would fight with one of the document's design
goals, which is to walk the reader through the build with rich context
- the "why it's this way" and the "what do I do if this fails?" - at
each step.

> Simplify the micro sd image creation process.  I ran across a lovely
> application - https://etcher.io/ - that makes it drop dead simple to create
> your micro-sd on the linux desktop, windows, macOS. Obviously CLI needs its
> own specific instructions - which belong on a separate page, for the more
> courageous/inquisitive users.

I don't consider this a simplification just because it has a GUI.  It's almost
certainly not going to have the intelligence about defaults that ddimage does.
In what sense do you think it is better, exactly?

> Then separate pages for the software builds - a GPSD page, top to bottom, an
> NTPD page, top to bottom, then both pages dovetailing to the pages for the
> integration process.

That "dovetailing" idea bothers me.  The narrative sequence is an important
tactic for conveying the meaning of the steps.  I will be very reluctant to
trade it for any organization that is formally prettier but not as good at
educating the reader.  You'll have to convince me about that.

> Then at the bottom the tweaking/performance tuning/FAQs. For example, rather
> early in the howto is a section 'optimize system performance', which is
> absolutely useful, but doesn't need to be detailed so early in the process.
> Tweak that governor *after* you've got the howto completed.

Well, not if you're OK with scattering multiple modifications on the same file
across different steps the procedure. That may be justified in this case, but
it;s not yet obvious that it is.

>                                                             Likewise, the
> 'Adequate power is important' section is near the very end - but it really
> belongs up in the hardware section, so people start out right.

Yeah, there's a better case for that.

> As you can see, I'm full of suggestions - that's the easy part!
> Implementation is a whole nuther can of bits, which largely hinges on
> finding the spare time and resources, which are always in high demand and
> short supply. Myself, I'm more of a grammar/syntax/readability realm, which
> is where most of my contributions have been. One thing I am always happy to
> do is act as a proofreader, anyone is welcome to throw changes at my inbox
> for vetting....

Offer accepted. :-)
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

My work is funded by the Internet Civil Engineering Institute: https://icei.org
Please visit their site and donate: the civilization you save might be your own.