Sunday, December 17, 2017

The Origins of Technical Writing

I never thought that technical writing had a special origin. I recognized the genre within non-fiction, because it is not history, for instance. If I had given it any thought earlier, I would have looked to the industrial revolution and to the explosion in science in the 19th century. But I did not. Only last week, writing a memorandum on the tasks I proposed to take on, it occurred to me that there must be some seminal book(s) that launched the study and practice as a distinct program. No surprise, a few online searches led to some good resources and to some authoritative nonsense.
"The Surveyor's Transit" Appendix I in
Theory and Practice of Technical Writing
by Samuel Chandler Earle

The best old book that I found was Theory and Practice of Technical Writing by Samuel Chandler Earle, New York: MacMillan Company, 1911 (301 + vi pages). I borrowed it from the UT Library. It was still catalogued under the old Dewey Decimal system and stacked in a section that smelled more like a library than the library. After an introduction of three chapters in 49 pages on basic principles of good writing, Earle gives criticisms of 24 examples, from the surveyor’s transit to the involute gear. The examples are informative on their own merits, fascinating examples of machines and methods of a century ago; and Earle’s commentaries are positive.  

Not so good was Technical Writing, Second Edition, by T. A. Rickard, New York: John Wiley & Sons, Inc., 1923 (337 + xii pages). (The first edition was 1920.) Rickard just gives examples of bad writing and explains why they are bad. He natters. He is not wrong, but neither is he helpful.

Technical Writing by
Sajitha Jayaprakash,
Himilaya Pub., 2008.
Both of those came up on an Internet search that pointed to an article on the history of technical writing from the website of Sajitha Jayaprakash (here). She is the author of several textbooks on the subject. She cites Rickard as the author of a previous work from 1908. I found a listing in  Rickard, T.A. (Thomas Arthur), 1864- Guide to technical writing. San Francisco, Mining and Scientific Pr., 1910. However, curiously perhaps, Jayaprakash says without further clarification: “Samuel Earle is hence considered to be the father of technical writing.” I agree that Earle does the better job, but Rickard preceded him. And I have no way to judge that first effort, though the second edition to the later publication does not hold much promise. I do believe that Rickard would have had harsh words for Jayaprakash who wrote: “Technical writing, as you know is systematic writing of instruction for the users to perform a given task. It is also about documenting information that users can use.”

The problem of when technical writing began as separate classification rests on the fact that for 2500 years, just about all writing was technical. The Gilgamesh and Argonautica and other myths stood apart from the vast body of philosophy for which there was no clear distinction between living the good life and discovering the mating habits of cetaceans. It was all knowledge. It was presented as fact, or at least as argument, and there was no doubt that it was all intended to inform the reader about the world and their place in it.

What changed?

The Wikipedia article on Technical Writing points out: However, unlike the past, where skills were handed down through oral traditions, no one besides the inventors knew how to use these new devices. Writing thus became the fastest and most effective way to disseminate information, and writers who could document these devices were desired.”

That claim is supported by an excellent article, “Constructing a Contextual History of English Language Technical Writing,” by Stephen Crabbe, Journal of Translation and Technical Communication Research, (Published byLeona Van Vaerenbergh and Klaus Schubert), Vol. 5. Nu. 1. (2012) Page 40, online here.)

Crabbe differentiates scientific writing from technical writing. The distinction is subtle. Aristotle on the parts of animals and Aristarchus on the motions of the planets were for the privileged few. More deeply, writing about the work of Eratosthenes of Cyrene in Circumference (reviewed here), Nicolas Nicastro asserted that as insightful as the ancient sages were, science was a modern invention. In that same context, Crabbe claims that technical writing originated with the Industrial Revolution.   

“However, it is generally accepted that the transition to factory-based, machine-powered industry can be traced to Britain during this period. The new machines could be invented, but workers with experience of constructing, operating and maintaining them did not exist. As a result, the pre-industrial oral tradition of passing technical knowledge from one generation to the next became less effective and relevant.
The Mechanics Institute was established in Glasgow in 1821, and its success resulted in the establishment of new institutes in rapid succession in towns and cities across Britain. Many leading manufacturers during the industrial revolution such as the Eastern Counties Railway, Royal Arsenal and George Stephenson and Company established new institutes. However, the purpose of much of this technical knowledge dissemination was not necessarily altruistic. Workers required instruction on how to operate the new mechanical inventions not for their protection, but for the protection of what were often expensive and complicated machines.
Manufacturers also needed workers who could construct and maintain the new mechanical inventions. Mokyr (2006) describes these workers as tens of thousands of literate mechanics and craftsmen who were able to understand technical writing and illustrations. The greater complexity of the new machines meant that oral descriptions of their parts were increasingly insufficient to enable mechanics and craftsmen to construct and maintain them.”

Be warned, though: That same Wikipedia article on Technical Writing also cites "A Brief History of Technical Communication" by Frederick M. O’Hara, Jr., of the Montana State University (Billings) College of Technology online here. That work is flawed by ideological and philosophical problems, but just empirically, O’Hara claims: 
“A case can be made that the first software documentation writer was Muhammad ibn Musa Al’Khowarizmi, a twelfth- century Tashkent cleric who developed the concept of writing a detailed process to be followed to achieve some goal, a technique employed in virtually all computer- programming languages today. He published a book about his approach and named his process the algorithm, a name that even today is used to refer to the mathematical application of this method.”

The truth is that the scholar did not give his own name to his method. The word “algorithm” comes from a Latinization of Al-Khwarizmi’s name. He may well have come from what we call Uzbekistan, but no source indicates that his family originated in Tashkent, an old city in eastern Uzbekistan that is the modern capital. Indeed, his origins were probably at the western margin in the place called Khiva (Xorasm; Khorasan). All we know is that he did truly work in Baghdad and lived about 780 to 850 CE (162 to 236 AH). And he wrote a book that we call The Compendious Book on Calculation by Completion and Balancing that was first translated into Latin by Robert of Chester in 1145. So, the book came into the West in the 12th century, but contrary to O'Hara's claim, the author lived some 350 years earlier.

Another common and erroneous assertion is that technical writing as we understand it began with us.  “However, most experts would agree that the golden age of technical writing started with the invention of the computer.
“1986: The American National Standards Institute (ANSI) released the Standard Generalized Markup Language (SGML), which became the basis of several subset markup languages, including HTML.” From “History of Technical Writing” by ProEdit, a contract and direct hire placement firm. The truth is that ANSI SGML was based on Donald Knuth’s TeX invented ten years earlier and enthusiastically adopted.  (See TUG the TeX User Group here.)

As noted at the opening, the earliest textbooks on technical writing apparently go back only to the beginning of the 20th century. But Scientific American was founded in 1845, and despite (or perhaps thanks to) changes in ownership, it has remained the longest-running periodical in America.  


Saturday, December 16, 2017

Austin Security Alliance

On Monday, December 11, 2017, members of 14 computer security organizations met at Indeed headquarters to launch the Austin Security Alliance. ISSA's president, Larry Moore, was the tip of the spear: this was his idea. But very many people were involved because they saw the wisdom in the project. With 20,000 to 30,000 professionals employed in computer security, Austin intends to be declared the Computer Security Capital of America.
DON'T PANIC was the cover band: classic 50s to urban.
As Larry and a dozen other organization officers and leaders explained in the opening presentation, the purpose of the ASA is to enable and facilitate cooperation across specialties. ASA maintains no membership of its own  and collects no dues. My perception is that it works. I should have intuited but did not know that we have a local ASIS chapter. It was nice to meet them. I was a national member for two years. Now, I have a reason to renew.

  • ASIS International
  • Association of Continuity Professionals – Capital of Texas Chapter
  • Austin Hackers Anonymous (AHA!)
  • Cloud Security Alliance – Austin Chapter
  • Electronic Frontier Foundation – Austin
  • Hackformers
  • Infragard
  • Information Systems Audit & Control Association (ISACA)
  • International Information Systems Security Certification Consortium (ISC)² – Austin Chapter
  • Information Systems & Security Association (ISSA) – Capitol of Texas Chapter
  • Longhorn Lockpicking Club
  • Open Web Application Security Project (OWASP)
  • Secure Austin
  • Texas CISO Council
TDEM 2017
BSIDES Austin 2016
InnoTech 2015
BSides Austin 2013
Securing Your Viper Against Cylons

Sunday, December 10, 2017


How the Martians Discovered Algebra: Explorations in Induction and the Philosophy of Mathematics by Roger E. Bissell (Amazon here in book and Kindle formats) delivers an algorithm for generating Pythagorean Triples. Central to the thesis of the work, Bissell explains how he discovered this by means of induction, not deduction. From there, Bissell takes the reader into number theory in order to validate his new explanation of the proper understanding of multiplication, and to challenge widespread assumptions about the empty set and infinity.

The relationships between music and mathematics go back to Pythagoras. So, this set of essays by musician Roger Bissell enjoys a solid foundation. Bissell also dabbles at mathematics and has several philosophical explorations to his credit, published in The Reason Papers and the Journal of Ayn Rand Studies.

Objectivism is an integration of rationalism and empiricism. Objectivism rejects the false dichotomies of Descartes, Hume, James, and the myriad other philosophers before and after. Consequently, Bissell and other Objectivists provide logically consistent, reality-based and practicable methods for understanding the universe including our inner selves. Objectivism is what the scientific method was intended to be: a guide to living.

That said, this book failed to convince me on several points with which I was pre-disposed to agree. And I concede that the ultimate failure may be mine, not the author’s.

Bissell begins with some techniques in speed math. These discoveries from his senior year in high school demonstrate his inductive method.  They also provide an introduction to his algorithm for discovering Pythagorean Triples. That alone is worth the price of the book. It is easy enough to explain, though hard to show with the typesetting available here. Basically, you want three integers such that a^2 + b^2 = c^2. Easily, there must be some number, x to begin with. The other number must be some number added to x that can be expressed as x+a, and the result of adding their squares must be some (x+b)^2. It all follows from there.

But I had a hard time following it. I tend to read at bedtime. So, I filled my notebook with pages with arithmetic when I was tired. I told Roger that his algorithms did not work. He asked me to send him PDF scans. I did. He corrected my homework. So, I agree that the Bissell Algorithm will, indeed, generate Pythagorean Triples.

Moving forward, Chapter 5, “Mathematics as an Inductive Science”, adheres to the Objectivist interpretation from Ayn Rand, Leonard Peikoff, and David Harriman. The traditional view of induction is expressed as the problem of the black swan: no matter how many examples of anything you gather, the next test can disprove everything you thought you knew. Induction, the traditionalists say, gets stronger and stronger as more examples are revealed, but final proof and final truth are always denied to us. This view is found weakly in the narratives of Richard Feynman and strongly Stephen Hawking's popular work.  (See “Questions about A Brief History of Time” earlier here.) The Objectivist interpretation is that induction is valid if and to the extent that the generalization from specifics is properly based on the correct characteristics. The problem with the black swan is that nothing about “swanness” requires “whiteness.” Swans are not essentially white; swans are not intrinsically white. On the other hand, Bissell points out that water is essentially and intrinsically H2O, which was discovered to be essentially and intrinsically 6 up-quarks and 4 sideways-quarks. Our better understanding did not invalidate the previous truth to the extent that it was, indeed, true.

From acceptable (if not obvious) Chapter 6, “Equations as Propositions,” Bissell moves toward infinity by discussing “Zero as an Operation Stopper” (Chapter 7, which is also about the number One), and the “fiction” of the mathematical Empty Set. There, and approaching infinity (Chapter 8), he loses me; and I am wide awake.

To me, his complaints about the concept of nothing, zero, and the invalidity of infinity and orders of infinity echo the arguments of ancients against the existence of atoms. If atoms exist as the ultimate particles of the existents we perceive, what is between the atoms? Many ancient philosophers rejected the idea of the void: “nature abhors a vacuum.” But if the universe is a continuity of atoms, why are we not locked in atoms like flies in amber?
The ancients (some of them anyway) denied Zero. How can you have nothing? From that comes a denial of the validity of negative numbers, irrational numbers, imaginary numbers, dimensions more than 3 (or 4 or 10), or particles that act like waves.

The problem is language. Language allows us to construct nonsense: Mathematics is green. The Catholic Encyclopedia offers some insight on understanding difficult problems. When we say that a brave man is a lion or a clever man is a fox, we know that we are speaking in analogies. “… but no Theist of average intelligence ever thinks of understanding literally the metaphors he applies, or hears applied by others, to God, any more than he means to speak literally when he calls a brave man a lion, or a cunning one a fox.”  (“The Nature and Attributes of God” ) Mathematics is not green, but 5 can be squared. Language is contextual. Language is analogy. Mathematical symbology is highly abstract and compressed. 

Words have meanings because language is based on reality. Whatever stars may be, intrinsically or essentially, categorically, provisionally, or contextually, stars exist and we perceive them. But we identify those perceptions in words not known 100 or 1000 or 10,000 years ago. In discussing the translations in their anthology of Aristotle’s works, Terence Irwin and Gail Fine offer this explanation about a single passage in Meteorologia.  Translated as nearly literally as possible, and allowing for alternative understandings [in square brackets]:
"Substance [essence] is said [spoken of], if not more-wise [several-wise], at any rate in four most; for indeed the essence and the universal and the genus [kind] seem [seems] to be substance [essence] of each, and fourth of these the subject." (See Aristotle: Selections, Irwin and Fine, editors, Hackett Publishing, 1995. Google Books here.)
I accept Roger Bissell’s point that the claim to “orders of infinity” is contrary to common sense. It is obvious that there are twice as many integers as even numbers. Nonetheless, you can, indeed map the “larger” set one-t0-one with elements of the smaller set and keep going forever… to infinity…

The central essay, “How the Martians Discovered Algebra” (Chapter 4) is a parable to demonstrate induction in mathematics as the doorway that opened to the world of algebra. 

Bissell's original algorithm for generating Pythagorean Triples is worth the price of the book. If you have any interest in epistemology, mathematics, or the problem of induction, then Roger Bissell's book delivers more for the money.

Previously on Necessary Facts

Wednesday, December 6, 2017

More on The Forever War

Admiral James Stavridis and R. Manning Ancell created The Leader’s Bookshelf (reviewed here) by polling four-star generals and admirals on their recommended reading. Also in that volume are suggestions by junior officers. Among those books was Starship Troopers, but not The Forever War. Science fiction has no shortage of war stories but these two are often compared and contrasted. 

As a writer, I like to think that I know good writing when I find it. In the stacks of my university library, I opened The Bluest Eye by Toni Morrison to a random page. No way could I ever write that well. Every word was perfect. Similarly, my mother passed Herzog by Saul Bellow to my sister who left it for me. Clearly, it was Nobel material. But neither did I actually read either one: the subject did not grip me. Forever War did. So, did Starship Troopers.

Forever War has an ineffable quality of first person narrative that opens the book with a  briefing and then puts you with the author in a field exercise in engineering, which is where Haldeman served. And that sense of experience continues, even though Joe Haldeman never jumped through a collapsar or wore a cybernetic fighting suit. Starship Troopers opens in an academy classroom, which was Heinlein’s personal experience at Annapolis. Again, the writer was never in servo-controlled armor.

Where Heinlein tells, Haldeman shows. The Forever War is the better read. Culturally, writing styles changed. Heinlein sounds more like Mark Twain and was intended for pulp magazines. It is cerebral. The Forever War was written from perceptions, reflections, and feelings.

Where Starship Troopers followed the formula of a John Wayne movie, The Forever War is closer in spirit to Catch-22 and M*A*S*H. The theme of Forever War is the senselessness of war. The plot is the story of a conscript who rises from private to major through no special talents, but who is lucky enough to survive a few pyrrhic victories. The theme of Starship Troopers is the necessity of military defense. The plot is the story of a volunteer whose training allows him to survive a series of engagements from which his leaders learn valuable lessons. Starship Troopers is romantic. The Forever War is naturalist.

I suspect but cannot prove that many young officers in today’s military recommended The Forever War, just as they recommended Atlas Shrugged. The editors of The Leader’s Bookshelf did not agree with the choice of Atlas Shrugged and therefore mischaracterized the book in their summary. The Forever War did not merit a mention.