Stratum 1 microserver HOWTO

[Paul Theodoropoulos]

On 7/31/2018 20:53 PM, Eric S. Raymond wrote:
> You big polishing patchset has just been integrated. It was excellent 
> work;
> thanks.

Thank you, Eric.

> 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.
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.
> Easily enough accomplished with :toc: in the options block.  I think this
> is a good idea, and have already made the change.
I saw - most excellent.I had no idea it was so simple.
> 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.
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.

1. Adafruit         V

2. Uputronics       -
          "The uputronics is shipped in two parts, the circuit board and
          header; the header is a press fit, no soldering required"
          "A standard case won't work due to the antenna connector, but
           that can be remedied with a dremel" etc etc

3. SKU 424254       V

That way, details that are explicitly irrelevant to my build won't 
clutter 'my' page as I'm puzzling through. The same can be repeated here 
and there to tailor a chunk of details to a particular build, while 
blocking in the common details, without slogging through details that 
mean nothing to my build - and which might/can be accidentally mixed in 
with the wrong details while puzzling through.

> 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?
A GUI isn't simpler inherently; but it can make the process a bit more 
approachable. I'm thinking in terms of the person starting out on a Mac 
or Windows machine, being interested in this process. On the other hand, 
while doing edits a short while ago I was reminded that the howto states 
that a Linux host is one of the requirements, so perhaps I'm off in the 
weeds. It'd be great if the instructions could be expanded to include 
folks on the former platforms - MacOS wouldn't be too tough with the 
built in unixy terminal shell, but Windows could be painful. Anyway.I 
live most of my life on the linux/unix shell, and often forget that 
that's not even available by default to some.

> 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.
Sure - it still sort of falls into the formatting-for-readability stuff 
I tried to express above.

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?

Personally - my experience - I've never even downloaded the clockmaker 
script. I wanted to learn all this stuff - dammit - and wasn't going to 
allow myself the opportunity to cut corners when I got frustrated.

  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.

>> 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. :-)

I'll try to keep my penchant for replacing simple words with $35 words 
under some discipline.

-- 
Paul Theodoropoulos
www.anastrophe.com