Stratum 1 microserver HOWTO

[Eric S. Raymond]

Paul Theodoropoulos via devel <devel at ntpsec.org>:
> I don't disagree. My thinking is more along the lines of _formatting_ than
> anything else. The page is very bare in most respects, and at times it's
> fatiguing to be piecing through part of it, and not having a visual anchor
> to hold onto as you switch between hacking on your cli and reading the
> webpage. I don't think any of the content needs to be removed, to be very
> clear about that. Only that more use of visual elements - different fonts,
> font sizes, color, indentation, etc - can help sort through the digressive
> (but still important/useful) parts. I think being able to present
> excruciating detail for the (N)eophyte's sake, and providing the visual cues
> for a person with N+x experience that this or that detail isn't necessary
> for them, can be salutary.

OK, I'd be open to adding some clarifying visual elements.

At this point you probably need to study up on asciidoc to know what is
possible.

> I understand that - I'm thinking - vaguely - of templating of sorts. List
> the three described GPS boards; each has a dropdown arrow, which 'reveals'
> the specific instructions for that particular board's hardware. So, say I
> bought a uputronics. (this is very hard to describe in ascii) I click the
> dropdown arrow to 'reveal' the specific quirks or whatever of the board.

Not a bad idea in itself, but we don't have the primitives for it
available, and can't get them without deopping to raw HTML/Javascript.
Which would open up several huge cans of worms around CSS and
Javascript portability.  Life is too short for browser-specific hacks;
I want to stay out of that swamp.
 
> > In what sense do you think [a GUI] is better, exactly?
> A GUI isn't simpler inherently; but it can make the process a bit more
> approachable.

But kill portability to no-window-manager installations of Raspbian.  I don't
like the tradeoff here; I think it's more important to mimimize the complexity
of the installed image, and its power budget. I actually want to go in the
opposite direction, stripping down the image further.

> A backfilled argument I could make is the existence of the clockmaker script
> - which may be far more tempting to the neophyte, who may figure 'screw all
> these details, I'll just run the script' (and not become educated in the
> process in the balance).  The howto tries to satisfy multiple audiences,
> which is by no means bad, but I think the problem is that massive spectrum
> there is within the potential audience. How easy should it be made? How much
> detail?

My design choice here is to supply just enough detail for troubleshooting - e,g.
so that the configuration is not opaque to the user abd he has some recourse if
things don't go perfectly.

>  I may be an outlier.  I may also be overthinking the shit out of this.  :)
> 
> > 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.
> 
> I don't see multiple edits on the same file as much of a barrier, myself. In
> terms of logical flow I think it works better. Editing the same file
> multiple times can be instructional in itself - 'oh yeah, i remember this
> file, the syntax looks familiar, I see how this modification fits into it'.
> 
> As above I may be an outlier.

Let's do the easy visual polish first and then revisit this.
-- 
		<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.