[TUHS] Re: Old documentation - still the best

[Larry McVoy <lm@mcvoy.com>]

Good writing is an art form.  I used to be awful, then I met Udi Manber
and did some work with him.  When I told him I struggled to write a good
paper (I was either a senior or a grad student, so not a lot of practice)
he was flabbergasted and said "writing papers is easy".  I said "do tell".
Here is what he told me:

A) You have to know what you are writing about, no amount of writing chops
will cover up a lack of knowledge.  
B) You have to have a good outline.  Organize what you want to tell
people and get it in the right order and with the right level of detail.

The outline is like the skeleton of a ship.  Once you have that, you are
just nailing on boards.  Same thing for a paper.  A good outline and 
good knowledge, now you are just typing and filling in the details.

But to get back to your point, Will, great writing is all of that but
just enough words, no more, no less.  You need skill to do that but you
also need to care about what you are writing, it's easy to write crap
if you don't care.  It's hard to write well, even with all skills, I
used to call writing being mentally constipated, the good stuff didn't
come out easily.

The early Unix papers were very well written.  The Bell Labs technical
journal papers about Unix are fantastic in my opinion.

On Sat, Jun 01, 2024 at 08:59:42PM -0500, Will Senn wrote:
> A small reflection on the marvels of ancient writing...
> 
> Today, I went to the local Unix user group to see what that was like. I was
> pleasantly surprised to find it quite rewarding. Learned some new stuff...
> and won the door prize, a copy of a book entitled "Introducing the UNIX
> System" by Henry McGilton and Rachel Morgan. I accepted the prize, but said
> I'd just read it and recycle it for some other deserving unix-phile. As it
> turns out, I'm not giving it back, I'll contribute another Unix book. I
> thought it was just some intro unix text and figured I might learn a thing
> or two and let someone else who needs it more have it after I read it, but
> it's a V7 book! I haven't seem many of those around and so, I started
> digging into it and do I ever wish I'd had it when I was first trying to
> figure stuff out! Great book, never heard of it, or its authors, but hey,
> I've only read a few thousand tech books.
> 
> What was really fun, was where I went from there - the authors mentioned
> some bit about permuted indexes and the programmer's manual... So, I went
> and grabbed my copy off the shelf and lo and behold, my copy either doesn't
> have a permuted index or I'm not finding it, I was crushed. But, while I was
> digging around the manual, I came across Section 9 - Quick UNIX Reference!
> Are you kidding me?!! How many years has it taken me to gain what knowledge
> I have? and here, in 20 pages is the most concise reference manual I've ever
> seen.
> 
> Just the SH, TROFF and NROFF sections are worth the effort of digging up
> this 40 year old text.
> 
> Anyhow, following on the heels of a recent dive into v7 and Ritchie's
> setting up unix v7 documentation, I was yet again reminded of the golden age
> of well written technical documents. Oh and I guess my recent perusal of
> more modern "heavy weight" texts (heavy by weight, not content, and many
> hundreds of pages long) might have made me more appreciative of concision -
> I long for the days of 300 page and shorter technical books :). In case you
> think I overstate - just got through a pair of TCL/TK books together
> clocking in at 1565 pages.
> 
> Thank you Henry McGilton, Rachel Morgan, and Dennis Ritchie and Steve Bourne
> and other folks of the '70s and '80s for keeping it concise. As a late to
> the party unix enthusiast, I greatly value your work and am really thankful
> you didn't write like they do now...
> 
> Later,
> 
> Will
> 
> 
> 
> 
> 

-- 
---
Larry McVoy           Retired to fishing          http://www.mcvoy.com/lm/boat