Joking aside, lots of military manuals share the trait of introducing their subject matter well, in order to ensure that whoever's using the material has at least a reasonably strong basis in the "what" and "why" as well as the "how" - I suppose ideally that's something that'd be covered in training, but also that manual authors don't assume they are writing for an audience that is guaranteed to have been trained. The result is often a supremely useful resource in whatever subject it treats.
Frankly, I can think of worse models for the technical documentation we as software engineers produce...
Also, I like the cookies. https://quartermaster.army.mil/jccoe/publications/recipes/se...
WHEN I WAS ABOUT TO BEGIN TEACHING at Princeton, my friend and mentor Sam Treiman called me into his office. He had some wisdom to share. Sam pulled a well-worn paperback manual from his desk and told me, "During World War Il the Navy had to train recruits to set up and operate radio communications in a hurry. Many of those recruits were right off the farm, so bringing them up to speed was a big challenge. With the help of this great book, the Navy succeeded. It's a masterpiece of pedagogy. Especially the first chapter. Take a look."
He handed me the book, opened to the first chapter. That chapter was titled "Ohm's Three Laws." I was familiar with one Ohm's law, the famous relation V = IR that connects voltage (V), current (I), and resistance (R) in an electric circuit. That turned out to be Ohm's first law.
I was very curious to find out what Ohm's other two laws were. Turning the fragile, yellowed pages, I soon discovered that Ohm's second law is I = V/R. I conjectured that Ohm's third law might be R = V/I, which turned out to be correct.
- They're organizations that have existed for as long as their countries.
- They're incredibly large.
- They have to communicate critical information to a very diverse set of readers.
- They iteratively update their approaches, over decades, often in direct reaction to the most stringent real-world tests.
... how could we not learn something from the systems they're currently using?
My favorite nuggets are (1) the glory of BLUF (bottom-line, up front; or an executive summary of everything to follow), (2) including a formal intent preface to any document (to guide writers and readers in what to include/exclude), (3) thoroughly defining terms (to avoid "we're using the same word with different meanings" problem), and (4) rigorously structuring information into separate sections.
Which isn't to say militaries get everything right all of the time. They do tons of stupid things. But dismissing or ignoring them as a source to cherry-pick best practices is shortsighted.
> ... how could we not learn something from the systems they're currently using?
You haven't noticed the aversion to the military, especially the US military, around here or in "academic" circles?
And what aversion there is seems to be a missing distinction between the military organization and military outcomes.
There are 1.3m active duty US DoD uniformed personnel. And another 1m reserve.
The bulk of those are performing support functions and keeping the whole organization running.
It's difficult for me to form any kind of ethical judgment about support folks, however the military is ultimately employed. And especially when weighed against the large number of tech careers that are in support of advertising/tracking.
I wonder if the next generation will invent their own version of this. The current 'trendy' one is tl;dr
It's one of these ideas that are universally useful, but get a different name in each context.
No truer statement about humanity has been spoken