My final “Managing Up” post for Steyer Associates offers an abbreviated look at earlier trends in technical communications. Here’s a longer meditation on being in the trenches over some of the most life-changing technical advances in the past quarter century.

A decade out of college, I first asserted in a job interview that I was a writer. Previously, my job roles had included editing—for solar energy designers, conservation policy advocates, and a couple of dyslexic physicists. During that “editorial” apprenticeship, I typically tossed 90 percent of what I received and rewrote it. That made me a writer, correct?

I faked my way through that interview and went to work for a local power utility, where I learned the basics of tech writing, before the profession had degree programs or professional associations.

The tech writing basics? Forget what your English teacher said: There is no practical use for creative, complex sentence structures in tech writing:

• Sentences in tech writing have no more than two main clauses.
• A sentence with more than two phrases should instead introduce a bulleted list.
• Each item in a list uses the same structure as the other items—parallel construction.
• A paragraph has 5-to-7 lines maximum, for readability.
• Readers scan, so each page needs at least one bolded line or headline, preferably more.

Halt and Catch Fire

My work with the appropriate technology folks led me to computer documentation, when personal computer software was just a wild and crazy idea. The first entrepreneurs I contracted with were building shareware, like Bob Wallace’s PC-Write. They’d left Microsoft as too corporate: there were more than 40 employees!

I then undertook contracting jobs to write Word 1.0 and Multiplan tutorials. We created user docs for software that would run on a top-secret system called Lisa, which borrowed GUI ideas from Xerox Alto—like a picture of a manila file folder to represent where files were stored. What I learned as a tech writer during that revolution:

• Present each instructional statement in a clear, consistent way, using concise verbs.
• Number items in a list only if the steps must be done in a particular order.
• Use the word “warning” only to advise that an action might cause physical harm or death.
• Do not wear a white suit to a press check.

The printed books from my best work in that era ended up in a landfill, because the products never shipped.

troff to WYSIWYG to XML

From those early basics, I continued to pass myself off as a writer and a manager of technical communicators. Subsequent lessons began to merge or cancel each other out:

• It’s possible to create great looking books without paying a typesetter.
• It’s possible to not bother creating printed books.
• It’s possible to survive without a production team, though it’s not a decent way to live. After Aldus was sold to Adobe and DEC VAX stations disappeared, no software company could be convinced to spend even 25 cents on productivity tools for documentation. (Shoemaker’s children going barefoot…)
• The writer should take a guess at describing how the pre-alpha software might work, and the editor will QA the text later against the beta software UI. Then in the next version you can—
• No, cancel that. You must write the instructions quickly and correctly the first time, because your alpha draft has already been localized into 13, 27, or 43 languages.

I remember one of my first hypertext projects, in the late 80s. Someone explained that each nodule of information was like a ping-pong ball with a dozen Silly Strings attached to other balls, all stretchy and interconnected. Then the Web appeared—made possible by the standard TCP/IP implementation in Windows for Workgroups and Windows 95, plus some browser wars. For users, GUI interfaces won; for technical writers, markup languages began to replace the glories of GUI text production.

 Standard, Generalized, Messed-up Language 5.0

Then one day I came to work and learned that we weren’t writers, editors, and localization professionals any more. We were all content providers. It seems that the Web consists of a series of ad frames, within which there’s a narrow column where content must be poured.

At the same time, the Six Sigma guys showed up with their MBAs and Key Performance Indicators.

The value of our professionally crafted words was not how well our writing solved users’ problems or described new cyber capabilities—because those are too hard to measure. Instead, the value of the content we provide must be measurable, not ephemeral:

• Reusable potential?
• Ease and speed of localization?
• Time elapsed until defect repair?
• Meet SEO targets?

Then the second shock waves of open source rolled over content providers: Hey, how about if we use community contributors instead of writers and editors and translators?

Many in the profession diversified at this point in tech-comms history:

• Become a UI designer: better UIs don’t need documentation.
• Become a programmer and comment your own code.
• Create videos or computer-assisted tutorials.

“Does Exactly What It Says on the Tin”*

So here we are [this was written in 2015]: we’re all content providers now. However, the key ways in which we still add value follow the same simple rules:

• Use concise, clear terminology—that the whole team follows.
• Use simple, clear sentence structures—that are easily understood by English-as-a-second-language readers.

Of course, clear terms and clear structures are key to machine-supported localization. And who besides us tech-comms folks are going to teach those machines what they must learn about successful language practices?

* “Does Exactly What It Says…” is a slogan from a British ad campaign that must have been created by Tina the Tech Writer.