[Cryptography] Readable manuals, and fixing bugs by documenting them

Tom Mitchell mitch at niftyegg.com
Tue Sep 27 20:53:12 EDT 2016


On Mon, Sep 26, 2016 at 12:17 PM, Bob Wilson <rwilson at wisc.edu> wrote:

> Just a couple of old-fogie thoughts... (These points came up in different
> threads, so saying "Re..." doesn't really work well.
>
> One of the bad things for manual construction was the development of
> documentation software. For this purpose I include everything from word
> processors through the various roffs and the like.



The quality of documentation is critical to the success of a product.
It can take many forms and be built with many tools but it is necessary.

A number of years ago I was trying to learn enough php to get some things
done.
My first five questions or so were not answered in the primary documents
written
by engineers but were answers to user comments (questions and answers).
Any
largish project should look hard at the php model and tools. IMO.

At a unix company 25+ years ago some thought I was a wizard because I
picked up a script that built an "apropos" data base.   It took a couple
attempts and got it baked into the product.  The quality of questions
to the company engineering by customers, users, internals and others
including internal support staff went up.

If you invents something you need to teach others about it.
Without the education component you are inflicting an adventure
game with no gold coins on people trying to get things done.

The authors of Frank and Ernest understood some of this
better than most managers.

If you are an inventor meditate on this often.
If you invest in inventors meditate one this more often.
http://www.thecomicstrips.com/store/add.php?iid=70205
"Look! I just invented writing! Thanks a lot! ... You just made everybody
else in the world illiterate!"

Do not get lazy,   User forums are full of cruft.
Documentation should relentlessly improve.
You do not want to allow any old edit.
http://www.thecomicstrips.com/store/add.php?iid=57512
"I'm not sure which, but he's just invented either writing or vandalism."

Tools are not magic but can tighten the turn around cycle.

Yes invent in quality authors and readers.
A good author can own the outside looking in perspective
in a company of engineers that own the inside looking
out view of the world.
User interfaces begin as engineering check lists and often
reflect the internals of the project.   A user interface by
its nature will be different.  They can coexist.





-- 
  T o m    M i t c h e l l
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.metzdowd.com/pipermail/cryptography/attachments/20160927/89f65360/attachment.html>


More information about the cryptography mailing list