Writers' Stories

STOBZ

2011-08-03T09:01:00.004-04:00

Something I did at Schwab - Steve and I were on a riff about information objects. He sent it to me the other day in celebration/commemoration of the hole in my head.

STOBZ means stobs which means the two by four stakes driven into the ground when laying off a house - transferring the abstract plan into physical reality. Stobs and batterboards define the extent of the house. Strings stretched between the batterboards define the precise dimensions.

Notice above that I left out the word "more" in my definition of a "steve".

There is a lot of circling back in this definition - recursion I think it is called. It made sense once - not too sure now.

E Books Riffs (and "Context Asides")

2011-01-21T09:21:00.024-05:00

(Quickly.)

Brian H sent me a thing about E book publishing - said he had gotten obsessed - that we needed to talk about it. Brian is great when he gets obsessed - he explodes with enthusiasm and energy. He cannot be contained in ordinary space.

I said sure.

Here's the link he sent...

http://www.bookbaby.com/?utm_source=CDBArtists&utm_medium=Email&utm_campaign=Prospect01)

I sent Brian's link to Bill M - who like me does traditional books via LuLu. Bill riffed on Brian's material. And he dropped off one of his exquisitely carved little stories.

Here's Bill's link...

http://bmooremiamifla.blogspot.com/2011/01/ebook-jungle.html

And here's me...

Two things.

Like Bill I have no e-book experience. But like him. I do have lot of experience writing and reading stuff that appears on computer screens. I have found that long, linear material - content that builds on itself doesn't read well from computer screens. Don't ask me why - everybody knows it. Maybe paper lets you flip back and forth, move in and out - continually orienting yourself, building a context for facts, ideas. All I know is that if the ideas are really complex, tricky - if the story is more than a few paragraphs I have to print it.

But some material works just fine - mostly short pieces whose context is immediate, not requiring thought but reaction. Bill's latest little story "Breakfast at The Orange Bowl" works. Some of my recent stuff - maybe "Lovely" might also fit this moldless mold. Certainly Richard Brautigan's little sketches in Trout Fishing in America work. Start anywhere and the words still hang together. The meaning - the message is like a hologram - embedded everywhere requiring only the reader's perspective to pop alive. This material is legitimate. Literary tweets. Haikuish writing for the fragmented reader - and fragmented writer (what I am doing here I guess).

But - and this is my second thing - would Brautigan find an audience in the world of online publishing? In this DIY (Do It Yourself) world not only is the writer his or her own publisher the reader is his or her own critic. The writer might be able to get anything published but the reader - due to the sheer volume of content available - doesn't always know where to find stuff worth reading.

That's the great thing about a real book store. Grab a cup of coffee, scan stuff that looks good, maybe catch the roaming eye of a literary lady in the next aisle over - "Hrumph I say you look a little young for Brautigan " (old man's grin/leer intrudes) "did your folks have copies lying around the house?"

Maybe that will be the next Big App - the Critic Bot. Software that roams the web looking for good stuff - maybe material satisfying some objective quality criteria - at least the latest reliable buzz offered by an algorithmically defined cool inner circle.

"Hey did you read E Book Riffs?"

"Context Asides"

(Less quickly)

A lot of this is about context.

Knowing Context

Knowing your context is knowing who you are, where you are - how what you are doing fits into the total of what is to be done - how ideas being presented fit into the total of other ideas. Without context you are lost, isolated - estranged. To be totally devoid of context is to be insane.

Online Help

Context has always been a big deal for those who write online help. What do you display when the user asks for help? "Context Sensitive Help" displays information about the current context of the system - what's being displayed, what's going on - maybe the field where the cursor is now located. Other forms of online help simply launch a new window in which is displayed on online book with information about the system. The online book will likely have an interactive table of contents, maybe a glossary. Related topics connected by hyper links. The online book will probably be designed to so that context of information being displayed is is clearly indicated through tabs, folders, topic headings - so the user doesn't get lost in the online book.

GPS Story

Last winter I used a new GPS unit to navigate my way though rural Ga (with a side trip to Al) then across Fl down to Miami. I was by myself and figured that it would be easier listening to directions spoken by the GPS than it would be to navigate a map and drive.

At one point I found myself in S. Ga on a two lane black-top road in the middle of pastures, fields, cows and the occasional out building and farm house. The GPS knew where I was, but I didn't. Zooming the display in and out did not seem to help. All I knew was that I was in S. Ga headed for N. Fl. I had no sense of context. I was not lost but I was lost.

Map Story

Later in the summer of last year I took another trip - this time to the Canadian provinces of New Brunswick and Nova Scotia with my friend in his BMW Z4 convertible. Instead of a GPS we used maps to navigate, deliberately choosing the most out of the way back roads we could find. One of us drove and the the other navigated - often never taking his hand off the map residing in his lap. Not once on this 4,800 mile trip did I feel lost, with no sense of context - no matter how backward the road or how far off the beaten path we traveled. At any time the navigator could see our road, find nearby intersections, locate alternate roads, towns, provinces, states - countries. All it took was a shift in focus - a shift in the perception of our context.

The Secret Grandiosity of Technical Writers

2010-03-21T10:33:00.006-04:00

I recently posted an essay (on another blog) about Lee Harvey Oswald, grandiosity and me.

Briefly, the premise is this…

Grandiosity is a game played with reality. It is the belief that the rules - the odds, don’t apply to you. That you are special. All grandiosity starts out as private dreams and schemes. It becomes public if the need is great (if the present reality sucks badly enough) and if a beneficent accident happens that suggests the impossible might really be possible. At that point - given talent, persistence and more luck, the dweeb might sprout wings - or pick up a gun.

The theme song of the grandiose person is the tune from the Man from La Mancha (“To dream the impossible dream, to fight the unbeatable foe, etc”).

When I suggested to a writer friend that tech writers are grandiose, she looked at me like I was crazy (a look that overtly grandiose people get used to). She said, “Isn’t that an oxymoron?”

I said, “No, no. Think about it. Don’t technical writers end up knowing more than anyone else? Don’t we have a better grasp of the product, the process?”

“Well sure, “ she acknowledged. “I have always said that tech writers know the process better than anybody. We have seen it all.”

“That’s it,” I said “That’s what I’m getting at. In our secret lives, we know that we are special. We are quietly grandiose - some of us anyway.”

She muttered, “They never give us credit for knowing anything.” And we moved on to another topic.

I should have told her a story.

Like many of my stories it goes back to the Time Of The Beginning when we were all working for Burroughs at the old Charlotte Merchandise Mart on East Independence. This was before we had split up into the Tootsie Room and the Pseudo Supervisors’ Rooms. We were in a big open space separated from one another by pieces of cardboard cut from packing crates. Paul Seid sat in his modified box. John Yankech used a section of his box to cover his desk like an awning.

It is John that I am talking about.

He was writing the Burroughs Hospital Information System (BHIS) Environmental Software Manual. Today it might be called an architecture guide. It described the underside of the system. How all the pieces fit together. The thing was - until John wrote his document nobody understood the whole thing. This expert or that might know how one piece worked and interfaced with a few other pieces. But nobody knew it all. John was blazing new ground. He became The Expert. He was The One.

The work was agonizingly slow; some days he wrote no more than a paragraph. But that was always a special moment. Filled with his own grandeur, John would announce to the room of technical writers - trolls hidden under and inside cardboard boxes, “Great Shit!”

And we basked in his glory, rising up momentarily from our boxes, knowing that we too were something else. That despite the odds, despite what the others might think about us, despite the lack of respect - despite the fact that we might not have the courage or inclination to pursue greatness, we were great.

That is what I mean by the secret grandiosity of technical writers.

Context Thread - November 09

2009-11-26T05:31:00.003-05:00

Introduction
This post consists of email messages exchanged between members of the Information Design and Architecture Special Interest Group of the Society of Technical Communications (STC). The thread started when I expressed an interest in "context".

Tom (me)
I have been wondering about tech doc context - has it gotten tighter, more narrowly focused over the years? Are fewer overview guides being written?

I'm guessing "yes" and "yes".

Such speculations led me to write an article "Context #1" which can be found at...

http://www.possumgolightly.com/possum-main.htm

The article contains this comment...

The Darwin Information Typing Architecture (DITA) standard for documentation seems task oriented rather than concept oriented. This latest scheme for organizing technical information is about doing the job rather than explaining the larger context of the job. Although DITA includes a concept category, the descriptions I’ve seen don’t seem especially interested in providing larger context.

Comments?

Val
I can't think of an equivalent area of study within the field of usability, but in grad school, I studied linguistics, and thought you might be interested in looking up "restricted codes and elaborated codes." This may also be related to your (and others') dislike of observing people on cell phones -- they sometimes seem to show off the restricted code, not sharing the context with everyone else, as if we can't be privy to the full intimacy.

I'm all for providing context when users need it, absolutely. But you can write more reusable sentences when you exclude it.

Erik
It is my experience and perception that there is still the same amount of context information written- if it can be. The DITA standard and how some of us proceed in file-based systems in recent years has definitely created a lot of emphasis on procedural documentation, but it may be deceptive to conclude that that has changed the amount or approach to writing context in heavily-typed and/or modular systems. The growing information regarding how people access Help for software in online and electronic forms, especially when the impact of newer search technologies is taken into account, has produced a new and more refined perception of the need for greater care, structure, and richness in the procedural area. So the situation may be more that software shops are producing more and richer procedural sections, rather than stripping down their context sections. At least that is the case in projects and products I have been involved with.

Mark
Erik's response noting "richer procedural sections" is cause for optimism, although I can't say it fits my experience. I've noted that in the drive to bitesize everything for display on screen, conceptual information can wind up hard to find and hard to absorb. It's a shame because with a reasonable investment in graphics and animation, some conceptual information can be
absorbed even more easily from the screen than from the printed page.

JoAnn
In 2000, the learning and training organization at AutoDesk released the online Learning Assistance. It contained two basic folders in the TOC, one for the tutorials and one for the concepts. The tutorials contained links to the concepts and the concepts contained links back to the tutorials.

The concepts were presented as animations with a voice over and the written text. They were superb for conveying a concept like Boolean expressions visually, especially apt for a visually oriented audience.

It’s one of my favorite examples in my Minimalism workshop.

Troy
I'm with Mark on the notion of using graphics effectively in conceptual topics. I think it would be an unfortunate design decision to not adequate include conceptual, background, or overview information in a task-oriented system, at least for a general online help system.

At a previous company, we worked in a distinct three-tier system of concepts, tasks, and reference by design. At the top, we included a minimum of conceptual overviews, which contained clear diagrams of complex architectures (in Visio for easy translation).

In the middle, we included a large number of procedural or task topics, really the heart of the system.

On the bottom, we had a mass of reference topics, which in this case included F1 context sensitivity for supporting UI topics and a large library of API topics. Concepts were constrained by procedures. We only included concepts that directly prepared users for understanding why they would use tasks in general, and why use one task versus another to accomplish a particular goal. The concepts themselves were targeted toward accomplishing goals (in this case creating
particular types of applications).

The help was organized functionally, with each function accomplishing a major user goal. The design supported different learning styles. Some people like to dive right in to tasks and only refer to conceptual information when needed. Others prefer to drill down via the conceptual information before trying tasks. Others want to work in the UI and get F1 help when needed, which links to related tasks and concepts.

The nice thing about this architecture is that it was easy to re-purpose the three-tier content to PDF as a kind of "book" presentation of the same content for those that liked sequential views for printing or reading.

I do not see the potential loss of conceptual information in a task-oriented system as having anything to do with structured documentation or minimalism in general, quite the opposite. It would be purely a design choice, sort of like choosing to not include a windshield when designing a new car. You can do it, but unless you like bugs in your teeth, I don't recommend it.

Tom
I was also hoping to hear from Troy. Excellent.

He and the others have fleshed out my vague observations. Yes, context/concept/background information might have been handled differently in the good old days. And yes, fewer broad-stroke overview guides and general introductions might be written today. However, in modern, well-designed systems, context info is probably handled better because it is to-the-point - relating specifically to the job at hand. In these systems the user has a better chance of getting to what he/she actually needs. And of course, as Troy suggests, the context-less doc forces users to fly without a windscreen, eating a lot of unnecessary bugs in the process.

All of which seems to be in keeping with my larger vague point - that context in our culture, like context in modern info design is also narrow and defined - which means that meaning more and more comes from the bits and pieces, not from the really big stuff - or something like that.

Thanks,

BTW -
Like other particpants in this thread, I have also used graphics to provide context for words. I found that including UML diagrams helps provide a graphical context for details that follow - which is not unusual since that's what UML is for. Below is a link to a sample design doc that uses UML (although this didn't always work because not everybody likes UML - even the bastard UML I sometimes employed).

http://www.possumgolightly.com/Samples/NCI_Specs/Sample3_TellerUseCaseandClassUML.pdf

I've also played with combining graphical context with "hot spots" linking to details. This sample is based on the structured writing thread from the STC ID SIG (occurring summer before last I think):

http://www.possumgolightly.com/StructuredAuth/WebHelp/StructuredAuthStructure2.htm

Troy
It was interesting for me coming from a hard core, high-pressure implementation background, then moving into company product documentation. In the implementation scenarios, documentation and training were entirely focused on immediate results so people could perform their jobs as quickly as possible--entirely mission critical stuff.

Task-oriented, structured documentation was the means to that end. We simply didn't have time to do anything else.

When I moved into product documentation and applied the same principles, what was suddenly excluded became very clear (beside the self-obvious stuff that didn't need to be documented in the first place).

I noticed that some writers had a particularly difficult time letting go of the more general (usually free-form) contextual information that was formerly offered in books or manuals. And many developers wanted all kinds of interesting treatises put in the product documentation and were saddened to see that there was no longer any place for their free-form content in the help.

The notion of product documentation became very restrictive to one idea: that the user of the product is actually sitting there in front of the product (right now) and needs to perform a job. They're probably already frustrated because they don't know how from looking at the UI. So get to it. The major challenge to writers was to predict where people would have difficulties beyond the self-obvious, rather than explaining the product in general. And the help system became the primary mode of delivering product documentation rather than large beginning-though-to-end books.

I consider the additional contextual documents as other content types, like whitepapers, articles, marketing materials (though more on the technical side), and even books. They are still legitimate forms of content and certainly belong in the greater information domain. The question is: where should they reside?

I remember one writer who simply could not divest himself of writing free-form contextual content, essentially disseminating the many interesting things he learned about the product. I told him the content was great--as articles, and to put it out on the developer web! But they were no longer "product" documentation per the three-tier, concept-task-reference model.

I think of the associated product content as existing in a number of interlocking domains, from hard-core product documentation, knowledge bases, marketing material, and company webs out to the ambiguities of Internet search. The totality of those domains form a large sphere with no defined edge. At the very core is the product itself, along with its embedded and online help. The closer we get to the product, the tighter the information, the harder the edges, for many reasons, such as legal, translation, maintenance, and company authority. Further away, things loosen up.

With the advent of the web, it is no longer necessary to include all possible content types within the product help itself. In fact, given the ever-increasing volume of content associated with complex products, it would not be wise. (On one legacy product I worked on in the past, the help content had grown to a couple hundred megabytes and was a significant portion of the product total!) In an ideal world, help search and web search are entirely complimentary. The main advantage of help search is crystalline focus on the current release.

So my advice to those who want to write for greater context: write books for O'Reilly (if you're in the tech field like me)! I love them. Just not in the product help. (Who wants to read a fat book in a little help window anyway?)

Tom
Thanks, Troy. I like your idea of "interlocking domains".

I can imagine the reaction of writers who wanted to do free-form concept material in a task-oriented environment.

I've had similar revelations and experiences but never formulated a consistent philosophy of the work - not the way you seem to have.

I remember writing "programmed instruction" for Cardinal Associates in 1972. Our shtick was this - that clients didn't owe us any money unless 90% of the students achieved 90% of the behavioral objectives. Which meant that we were very careful defining the students and objectives and everything we wrote was targeted toward that end. Although many of us (including some clients) might have wanted to provide neat background info, nothing was included that didn't move students toward final post tests (and our payment).

Then there was the time at Burroughs when I was doing field guide tables and documented the Name field thusly: "Enter the user's name in the Name field". As one of our writers wrote in his book, "Nothing more need be said."

And in more recent years I ended up at Schwab developing InstallShield installation programs and the accompanying documentation. Part of my job was to sit in on the first few installations of each release to verify that my materials worked. Which meant I could personally expereince the ways that my programming and writing could confuse people. If I hadn't t known before I was reminded of just how important it is to provide only the essential information. In these cases the users knew their own context - it was my job to provide programming and writing for various possible contexts and to get the users to the right place in the least painful way. The last part was the toughest - it took a while to finally get it right.

BTW - As I've done in a few previous discussions, I'm going to collect the elements of this thread in my blog, Writers' Stories (http://writerstories.blogspot.com/).

Wiki Thread - June 09

2009-06-09T15:18:00.019-04:00

Bartleby the scrivener - who famously said, "I prefer not."

Introduction
This post consists of email messages exchanged between members of the Information Design and Architecture Special Interest Group of the Society of Technical Communications (STC). The thread started when one of us (Lee Eubanks) asked about "possibility of replacing traditional help (print manuals and online help systems) with internal and external wikis".

Lee's question spawned a response which spawned a response which spawned a response, sort of like a musical riff or improvisation, or maybe the evolution of a chaotic system - although I think we stayed on this side of order.

Ostensibly about using wikis , this conversation was really about how to convey information in our brave new world.

The three main issues seemed to be...

How well do wikis work as collaborative tools?
How well do collaborative tools work for producing external documentation?
How well do "free" writers ( subject matter experts, users) work for producing external documentation?

The answer to all these questions was a qualified maybe.

In the experiences of our group, wikis haven't worked so great, collaborative tools are good for internal not external documentation, and free writers - well, you get what you pay for.

However, the group also acknowledged that applying the principles of good information design ("minimalism, structured documentation, user goals and supporting tasks" - Troy) would go a long way toward alleviating these ills - perhaps making possible the trend I wondered about in the previous post Slow Motion Black Swans - Tech Writers and Typists...

Enjoy.

Notes:

Tech writing (the bastard stepchild of 20th century system complexity) has always needed information and places to put it - virtual (and real) cubbyholes, file cabinets, etc. Maybe what Troy and the other information architects/engineers are getting at is that if the cubbyholes are well designed, the source of the information is not so important.
Posts in Writers' Stories are generally from the "underside of technical writing". I am not sure where this stuff fits.

Lee Eubanks - Start of Thread
I've never sent a message out like this before to the group, but I have a question that I need some feedback on. I am starting a new job tomorrow, and one of the things I've been asked to review is the possibility of replacing traditional help (print manuals and online help systems) with internal and external wikis.

Keep in mind this is a small company with two SaaS healthcare facility softwares. Currently, the help systems are not even context-sensitive, and the manuals are far too large and cumbersome. The company has apparently been implementing an internal wiki (which I have found useful in the past), and upper management has been sold on the idea of using external wikis for product documentation by the company they purchased the software from.

The idea is to centralize the documentation (which I view as being a good thing) and make it easily accessible for SMEs and BAs. The wiki offers a version control system, but my fear is just how accessible the documentation would become. People who have no business updating the help would be able to make changes, and that seems to be an issue from my perspective.

Furthermore, I fear wikis require far too much from the users and expects too much out of them. I'm not sure where the users fall on a technological savviness scale, but I suspect such a change would greatly inhibit their workflows and training new employees.

Am I being too paranoid? Does anyone have any experience using wikis as the only form of help for a company? What are your thoughts and initial impressions about it?

Thanks so much!

Ginny Risk - 1
I think the first question is the feasibility of using external Internet based help. This requires that users have external Internet access while they are using your software, and that their bandwidth be high enough to make this appear seamless. If you have that, you can of
course rig something up, whereby you provide precise URIs from within the application and an easy to use search page for 404 errors.

Also, find out why they want to use a wiki for help. What do they most want to achieve. Then assess whether the wiki is the best way to achieve it. The thing about using a tool to provide help within the app is that you can have automatic link checking. If you use a separate system, you don't have that. The wiki is good for managing access to its own pages, but you need to manage the links from the application.

If it's a question of users needing explanations for, say, the labels they have on widgets and options, where they might search on the label word in the wiki, you might want to look at the probability that something is wrong with the labels in question, and if no better label text can be devised, at least explanations can be provided within the app, for instance by roll over text. If it's a question of lingo that people don't understand, look at that first. A wiki that uses the same
lingo is no help.

Ginny Risk - 2
I didn't address the question of lots of people being able to update the help. You can configure that, right? Why does management think they want lots of people updating the help? That would be a red flag for me.

Maybe they want a wiki that developers can update as input to you. My experience is that this is not likely to be helpful. What is the incentive for the developers to keep their feature descriptions current? In this case, suggest an internal wiki and you still control the external content.

Tom Weathers
Although maybe a bit of a stretch, your problem seems to be an example of an issue I raised in a previous post...

Slow Motion Black Swans - Tech Writers and Typists...

... about a trend toward using SMEs as content authors. (I'm basing this on your statement "...and make it easily accessible for SMEs and BAs".)

If that is the case, I'd try to get involved in the wiki design, ensuring that...

Content authors (no matter who they are) are restricted to producing information in the smallest chunks consistent with good design. Paragraphs are easier to write than pages and writing deficiencies will be less obvious.(Making content creation easier helps ensure it gets done.)
Context material (produced by the best writer - you) conceptually ties all the chunks together.(Unaffiliated chunks are very confusing.)
Search tools allow users to find what they need among the chunks (if the users can readily find good information, they won't care so much about awkward writing).
A staging area is provided so that content does not go out without being edited or reviewed - or at least looked at by somebody.

Good luck,

Troy Klukewich - 1
I'm all for users supplementing help through various vehicles outside of help. I just don't think they should be replacing the help or core documentation.

On the other hand, if the help hasn't been particularly useful in the first place, then maybe someone else can write equally questionable documentation for free. (See my response to Tech Writers and Typists.) I get the economic driver of that idea. I don't recommend it, but I get it.

After the success of Wikipedia, there's been this idea floating around for years that customers and maybe other folks on the team can do the product doc--basically for free! There are also cases cited, especially in the open source community, where a developer community maintains the documentation, apparently for free. So, supposedly, they don't need writers.

Besides the fact the no one actually pays for these particular examples, there are two immediate responses that I have.

1. Wikipedia does not closely correspond to product applications, especially process-driven or lifecycle applications. It is essentially a large store of short articles on defined subjects. I think it does a decent job as such for a quick look-up of facts, though I don't think I would cite it as an authoritative reference for those (hopefully accurate) facts.

Would I want to use Wikis for mission critical product deliverables and processes? No way.

2. Though it is better than nothing, few people actually think that open source documentation is particularly good, let alone a model for all industry products to follow. It's what you do in a pinch when you don't have paid writers around (or anyone else that's paid). As for users, you had better already know what you are doing to make sense of a mass of reference-oriented open source material. If you are lucky, there may be some getting started material available. Most of the time, you're on your own.

Many developers on open source projects will admit that documentation isn't their thing and they'd really rather be doing something else if they could (like coding). They do what they can given the resources available. I consider open source documentation informal. API documentation can be okay in the open source model as developers are closest to the code, though even there they can end up losing the "user" context of a developer operating "outside" the object and its initial design.

I have this strange idea that customers should be able to dig into core functionality within minutes of first starting up a product. They should not require hours of reading and hunting around on websites to figure out core functionality. Once they understand core functionality as delivered with the product, they can go out on websites to find corner cases and particular real-world applications that others have experienced.

There are other issues to be concerned about in turning the documentation over to the user community.

Who owns the content? Who is legally responsible and liable for the content? And will you ever have to translate the content?

I love translations, especially expensive ones. When suddenly after years of English-only deliveries, products suddenly need translation, the hidden cost of years of inefficiencies suddenly blooms large. When multi-million dollar translations figure into the equation, people suddenly start asking questions like, "Who is this documentation for? Is it doing anything? Is anybody reading this stuff? How useful it is it by the way? Can we dump it without anyone noticing? What do we actually need to keep and translate?"

Good luck having constrained translation costs and budgets with wikis. Standardized, simplified language? Consistency? Minimalism? When translations are part of the picture, quality has a visible price.

Even if a product doesn't have translations, I believe strongly that it should be designed as if it will, including the documentation (I consider the documentation--or knowledge transfer--part of the product). Because so far I've dealt with a tremendous number of products that eventually required translation and all of them had huge cost issues to resolve. Most companies want their products to be successful and expand into international markets--eventually. The documentation is a critical component of product growth.

For some projects, documentation in effect forms a kind of legally binding contract with the customer. So far, every project I've worked on has documentation to this effect. It states that Product X does so-and-so, so it better do so-and-so, because if someone buys the product and their company experiences a catastrophic failure due to so-and-so not actually being in the product, guess who is going to get sued?

Do you really want a random user community controlling what the documentation claims? Or having some rogue with a hate on for the company hijack a page and make all kinds of strange claims? Sure, you can fix it later, once you know you have an issue, but by then it could be too late. The damage is done.

On the other hand, putting a huge, legal disclaimer on every posting that the wiki documentation implies no connection with the product won't fill customers with confidence, and confidence is a critical success factor for any product.

There is also a timing issue. It might be a good idea to document new features and capabilities at the same time as the product goes out. Having a random user community write to a strict schedule is a hard sell. Yes, there might be a lot of initial enthusiasm from super-users to get the early scoop, but I have found from personal experience that non-payed contributers can quickly lose interest and accountability when things get tough and they have to get back to their day job.

Finally, what message does a wiki send to customers? Maybe my opinion will change if I ever see a successful wiki model, at least for large corporate-oriented product deliverables. I'll honestly be interested in how it works to effectively replace documentation. So far, my conclusion is that product wikis are amateurish. I wouldn't take a product seriously that depended on a random user community to document functionality. Doesn't the company think its product is worth some professional attention?

If that product had no financial value with no implied warranties, was reasonably small, and was just for fun, maybe wiki-doc would be fine.

Finally, I read user-submitted material all the time, especially for corner-cases or real world experiences and problems. But I still expect a concise help system to cover the basics and a whole lot more with the product itself.

As for internal wikis, they're great. Use them. They're good for project-related tracking and information exchange. Writers can glean useful info from developers and SMEs for professional positioning as an external deliverable. The developers and SMEs don't have to worry about external audiences and can communicate what is needed internally. Writers can convert that information from internal to external content. (There's a big difference.)

Internal information wikis: Thumbs up.

External "documentation" wikis: Thumbs down.

As an alternative to the external documentation wiki, consider posting the help content to a website with a commenting capability. This is a great way to get feedback on your topics. Customers can also add their own examples, which are really useful. It is also clear who writes the documentation content (the company) and who writes the comments (the users).

Now, if users want a wiki in addition to the doc, as a value-add, maybe for their own articles, great. Go to it. I'd happily incorporate ideas and incorporate them into the core documentation, always with an eye on the new user encountering the product or a feature for the first time.

Customer dialog via wikis, user webs, newsgroups, blogs, and surveys is a great thing. I'm just under no illusion that these vehicles perform the function of documentation.

Karen Bertram
Neither of those issues---SMEs as authors nor wikis as information deliverables---is necessarily bad. But like any writer working in any authoring/publishing tool, if the users' goals and tasks are assumed rather than known, and if the information structures aren't defined such that users can't easily find what they're looking for, you're in trouble.

We use MediaWiki as a content collaboration environment---a scratchpad of sorts. It works will for an Agile shop where everyone's supposed to be able to contribute fairly equally. The biggest problem I see is that SMEs often don't know what to write, so they tend to write about **what's been built** rather than **how to use it**.

If I were in your shoes I would turn my attention to making sure users are soundly understood and build user goal and task models to drive content development. I'd also make use of DITA to define information types and their required content. "Templatize" these information types so your content authors can follow patterns. Think of yourself as the information engineer.

Eddie VanArsdall
Lee, you have received some great feedback from this group on the subject of wikis and user-generated content. I also recommend that if your company plans to implement a wiki, they need to carefully identify the problems that they expect the wiki to solve and decide whether it is the best solution.

I read recently that 80% of wiki installations fail. I have experienced several wiki projects that suffered from the "build it and they will come" syndrome. Even the more successful implementations I have seen don't always gain momentum right away.

I'm a regular user of social media apps and appreciate how they are creating new and diverse roles for our community. I'm all for encouraging users to contribute to a product's knowledge base in various ways. But I still believe that information architects need to oversee the structure and organization of the content. While wikis are an open, collaborative platform, they often suffer from a lack of organization and focus.

Your company should also take into account that allowing users to contribute content doesn't guarantee a significant level of enthusiasm from your user community. You may have a few regular contributors, but the majority of your users may not want to contribute. The level of participation can depend somewhat on their enthusiasm for your product and whether they want to actively participate in its development and improvement. I still believe that for the most part, they just want to use the product to get their work done and be able to give feedback.

Troy Klukewich - 2
I'm genuinely surprised that the implication follows that 20% did not fail. I'd love to see even one that succeeds and under what metrics and for what kind of product. I have a hat nearby and am fully prepared to eat it. (I admit, it is made out of straw.)

But I still believe that information architects need to oversee the structure and organization of the content.

The point about architecture is critical, the secret ingredient that many non-writers and even many writers fail to appreciate. All else being equal, architecture makes the difference between material meeting customer's real world needs and goals or not. It's a bit like how you can have all the right ingredients and still no cake without the activating oven heat.

I was sharing an offline story with Tom who posted "Tech Writers and Typists."

On my first tech job, I worked for a company that put all of its documentation on the web. We didn't do this because we were cutting edge. We did this because we were cheap and couldn't afford the paper!

The good news is that we had great web tracking and could literally see user trails through the content. Imagine my surprise after working months on new documentation to discover that no one, literally no one was reading huge areas of the content.

Now, to be fair, I discovered that in some cases, the lack of readership was simply due to poor navigation structure such as vague titles, incoherent TOC structure, and poor linking logic. A few tweaks and suddenly we had a flood of readers of the new content.

In a few cases navigation adjustments did not solve the problem. My conclusion? The feature was either self-obvious and didn't need any documentation or (gasp!) the feature wasn't being used.

Two points. Point one: It is essential to get user feedback to validate the utility and structure of the content. Point two: architects are sensitive to the need of good architecture. It isn't enough to dump content into a huge garbage can and let users root through it with a search engine.

And I shared this story with someone else who responded to me offline:

I remember one time when I was doing a stint at [Famous Tech Company that Shall Remain Nameless to Protect the Guilty] my manager gave me this dog of a financial course to fix. It was consistently getting the worst ratings of any course on their listing. They couldn't understand how it could be so bad. It was written by the developer and was surely technically accurate. I held my tongue of course when I heard "the developer wrote it," big hint right there.

Even before I reviewed the course I knew what would be wrong with it. Yes, it was a pile of technically accurate tidbits of apparently unrelated facts. I went in there, put a lifecycle on it, reorganized the facts to follow the user flow, and added a few connectors to pull it all together. It was maybe the easiest project I've ever worked on.

The next quarter, the ratings went from the worst to the best in their history. That's the difference architecture can make.

Two more points. Point one: User ratings are essential to track the usefulness of the documentation. We can't tell if we're making a difference with updates if we don't have metrics. Point two: The only thing I really did in this particular case was add some structure that mapped to a hypothetical user's real-world experience of the product.

Technical accuracy, while necessary, is not sufficient, a critical fact that escapes most developers, many SMEs, more than a few product managers, and even a few writers. Users know well enough when architecture and context is missing, but typically do not know how to diagnose the solution.

I'd love to see a bunch of random office workers building a skyscraper. We should not be surprised when the building does not stand. While I am all for organic, agile, bottom-up processes, some things still require an overarching vision and a deep understanding of craft to be useful.

Erik Reel
I feel Troy brought out some critical issues regarding wikis that are often neglected.

There are also serious, I'll call them "sociological" issues, in terms of implementation of wikis and the corporate culture. For a very good source discussing this area, as well as implementation examples that help round out a lot of Troy's comments with real-world experiences from a wide variety of sources, I recommend Stewart Mader's "Wikipatterns" (which is NOT a pattern book
a la system design).

I love translations, too: they immediately highlight and magnify the cost-equations in a way that make it easier to justify to executive management what we do. I also try to always write for an international context: these days, eventually any good product or service is going to desire or deserve an international market and it can be very painful to retrofit this attitude and the appropriate techniques and standards onto a large library.

The wiki question tests a very important architectural idea in the construction of external documentation systems: the distinction between production and delivery environments. Wikis tends to blur this distinction and can lead the unwary into a nest of evils. Usually the folks driving the wiki initiative do not understand the distinction in the first place, let alone the huge problems created by ignoring it.

I also agree with both posts that suggest finding out first what the real requirements are. What people who want wikis often really want are reduced costs, faster output or throughput through the entire product production cycle, better or wider SME utilization, and some sort of web-leveraged, real-time delivery mechanism (real-time as in, available as soon as produced, not whenever Engineering gets a platinum build and it weaves its way through the
product-release processes) for the product documentation.

A wiki or any sort of "open-source" production environment will have problems with most of these requirements. Open source will also have problems with getting anything out in a timely manner, and of course, never by product release. By the time public sources write about a feature, it is because the lack of knowledge-transfer has already caused a lot of problems and cost a lot of time and money. What the wiki as documentation approach ignores is the sociological aspect of the public writing sources - they tend to be crisis oriented, and only respond to situations that have already escalated further than you would want for the product that is supplying everyone's bread and butter. A big part of why we have documentation as a knowledge-transfer solution is so that we prevent these types of escalations and the consequent Support and loss-of-market costs associated with them.

As I read it, the original question was driven in part by a need to supplant or improve a Help system or documentation that didn't seem to be used or helpful. Well, a lot of times, one of the major ways to make documentation more helpful is to supply really good use-case context with "idiot-proof" step-by-step procedures. Good luck getting public open source authors to supply that kind of procedural writing - writing such procedures is a highly-prized learned skill
that almost no one possesses naturally, but a lot of better shops go out of their way to train their writers for. It is one of the ways we've traditionally earned our keep.

Other aspects of good online documentation have already been mentioned, such as minimalism, that make a system really hum. Oh, and one last thing regarding searching: Search engines and searching technologies can be vastly enhanced by specific practices and standards in the writing - naïve writers will NOT write documentation that optimizes search-ability. And I mean the ability to produce a product information system where anyone can quickly get to the information they need, not sift through twenty thousand responses or do three searches and not
find any response that answers their question.

Troy Klukewich - 3
Great post, Erik, and I couldn't agree more.

Good luck getting public open source authors to supply that kind of procedural writing - writing such procedures is a highly-prized learned skill that almost no one possesses naturally, but a lot of better shops go out of their way to train their writers for.

Yup, I received explicit training in my early SAP days (in a prior life) from an enterprise documentation company that had already learned what worked and what didn't work. Minimalism, structured documentation, user goals and supporting tasks were the name of the game for mission critical implementations. So called "traditional" documentation (systems oriented rather than user oriented, abstract, without context, lots of facts and reference) simply didn't work in actual practice.

I got to see first hand how customers received goal-oriented documentation versus traditional documentation. It was literally a binary operation: worked (goal orientation) | didn't work (traditional).

Lee Eubanks - End Of Thread
Thanks for all the feedback. It has been very helpful.

I survived my first day and plan to incorporate a lot of the information you all have offered me when I speak to the Directory of Product Strategy next week about this issue.

The idea behind all of this is upper management's dissatisfaction with the documentation that currently exists: over 2,000 pages with a lot of redundant content + an online help system that is not even context-sensitive.

It seems the previous writers in the company just kept adding content over and over to the Framemaker books.

My first task will be to assess the user guides and determine how to eliminate redundancies and increase the efficiency in the knowledge transfer process.

With the wiki, users would not be allowed to contribute to the content, but rather would have "public" sites within the wiki as their own forum. I fully support the idea of providing an outlet for user interaction and collaboration.

I believe once I provide a ROI presentation on single-sourcing (would love to implement DITA), I can change their minds about the direction our documentation needs to take. If anyone has any experience providing such a report, I'd love to hear about it or see an example.

Also, I know the latest versions of Framemaker support DITA, but does anyone have experience using DITA for Framemaker and utilizing Webworks to create online help? Those are the current softwares in place (though really outdated versions), and currently there is no structured authoring being used.

Thanks again folks,

Lee Eubanks

Response to Tech Writers and Typists Post

2009-06-08T08:39:00.006-04:00

This is a response by Troy Klukewich, an Information Architect at Oracle, to my post...

Slow Motion Black Swans - Tech Writers and Typists...

He wrote this as part of a dialog about my post in the Information Design and Architecture special interest group of the STC. I'm including his response as a separate post because it is too long to fit as a comment to the original post.

I think maybe his answer is better than my question.

Thanks, Troy.

So to answer your question, my guess is that a slow-motion black swan is happening.

In terms of information architecture and technical writing, I'd say, yes, the industry is changing and has been for some time. I'd say that a lot of the UI-type documentation that so many writers have been doing is diminishing in importance, especially with the advent of "self-documented" web interfaces.

Thank goodness. I never found documenting user interfaces to be all that interesting in the first place. It doesn't surprise me that so much UI-driven documentation is being outsourced. I personally don't think much of the kind of documentation we've been doing has much value in the first place. No one notices that it's gone if it wasn't performing much in the first place. It simply wasn't that useful.

As for documentation by the pound, it is a waste of time. I'm surprised that companies can still afford to throw money away on doing useless things. There's this old idea floating around that we need to produce lots and lots of "documentation." I say, why? What for? What's it supposed to do exactly? Is it doing it? Is it still doing it? Things change. Users change. What worked ten or twenty years ago may no longer be working.

I would put UI-type documentation and documentation-by-the pound in the "typing" category, a brief blip in history with other processes eventually surpassing it. And don't get me going about "formatting" and making stuff look pretty. Goodness. If I wanted to be a make up artist, I'd be in movies.

The only kind of documentation and user assistance that counts is the stuff that customers find genuinely useful. Shame on us if we don't insist on verifying that we're doing is mission critical.

If you aren't working on mission critical processes and knowledge, your job will go away. And even if you are, companies do strange things. Make sure that the company knows you are working on mission critical deliverables.

Given that so much documentation that has been produced hasn't been useful in the first place, companies will see how far they can go to cut corners now. They are getting away with a lot at the moment because much of the documentation we've been producing isn't mission critical. It just takes up space. If it was mission critical, people would notice right away that it was missing.

At the same time, companies will fail to recognize cause and effect relationships. Cut into the mission critical knowledge transfer too far with useless, low quality content and translation costs go up, often far in excess of the cost of an entire writing department per year. Penetration of foreign markets fail. Support costs and crisis management increases to project-threatening levels. Training needs explode (because the training is doing the job of documentation now).

There is no escape from the costs of knowledge transfer for sophisticated products. The cost merely gets displaced from one place to another, and extrapolated to the degree of lack of attention.

Meanwhile, customers are resorting to all kinds of theatrics to figure out how to use increasingly sophisticated products. In the worst case scenarios, studies have shown (I think it was Gartner, but it's been a while) how multi-million dollar projects have failed due to underestimating the importance of documentation and training--in other words, mission critical knowledge transfer. This is especially true for time-sensitive projects where people can't wait for some leading edge user to eventually figure it out first on their own and have Google pick it up.

So I would say that we should all insist on verifying the utility of what you are doing before it is too late. Don't be caught designing and writing useless crap that no one reads. It happens. I know. I've written some of it myself. Fortunately, I was lucky enough to have stats that proved that no one was reading what I was writing, so I was able to address why.

Since those days, I have focused on projects that require critical knowledge transfer. I don't want to write the kind of stuff that can be easily outsourced or that a non-writer can write with sufficient quality to pass. I like to go for the complex difficult content that requires deep analysis and true architecture and writing skills.

Eventually, companies will figure out what really is essential to deliver along with the product (not later in some user group or wiki). I suggest we all beat them to it and be leaders. Figure it out yourself. Check, recheck, and recheck with customers. Don't believe anyone else. Their opinion doesn't matter, only the customer's response and need.

I ask these questions of myself constantly. Where can I go to generate the most value? What can't be dropped or easily outsourced? What does the customer really need today? These are the kind of questions that information architects and writers need to ask. The answers are a moving target through time.

Really, we're getting to the point where information architecture surpasses technical writing. We all need to be architects now. In fact, when I mentor newer writers now, I insist that they think like architects from the get-go.

The time of typists, formatters, and user interface writers is gone.

Slow Motion Black Swans - Tech Writers and Typists

2009-05-27T09:20:00.058-04:00

In his Black Swan book, Nassim Taleb mentions the possibility of black swans (unexpected events) that move so slowly people don't realize what is going on.

I wonder if that is happening with technical writers. Are tech writers (as writers) going the way of typists? Are the same pressures at work?

Ancient History - At one time, typists were found in every office that produced written output. The "stenos" (or stenographers) were usually female, and toward the end of that era, usually people of color. Except for journalists and some authors, most writers created longhand drafts which typists transcribed. By 1979, the Burroughs development center in Charlotte where I worked had six typists to handle the output of 14 technical writers. The writers were not even given typewriters (we brought our own machines from home to do drafts). A writer's job was writing, not typing. Most older writers (like me) never even learned to type. I still use a painful hunt and peck technique involving two or three fingers.

The demise of typing as a profession probably started in the 1980's. Nobody said "Hey, we are in the middle of an office paradigm shift." We just looked around one day and the typists were gone. But mostly we didn't even notice. That's how slow motion black swans work.

Economics and word processors pushed the typing trade toward extinction. Word processors allowed even bad typists like me to get by. The files I created, no matter how painfully done, were no different from those created by typing professionals. It did not make economic sense to have two people (typist and writer) doing the same job. Plus, not only could the writer do the typing, but the document layout - helped along of course by software templates and tools.

The same combination of economics and technology might be pressuring the writing side of technical writing.

That tech writers even write is due to the sorry quality of much information provided by our subject matter experts (SMEs). Often it does not even exist in written form, being grudgingly provided in infrequent, ill-tempered interviews. SME's, buying into the myth that they can't write, gladly relinquish documentation responsibilities to technical writers. And of course, it is true that most technical writers write better than most SMEs - just as most typists typed better than most writers.

However, what if there was some way - some computerized way of making it easier for programmers, engineers, and other experts to describe their own work? Writers would still do the document design and editing - maybe overviews and summaries, but the content would come primarily from those who know it best. Seems like a good thing - at least from an economic point of view, maybe even from an information standpoint.

Two technologies have emerged in recent years which might make this possible (leveling the playing field for tech writing, creating a Tom Friedman style tech writing flat earth)...

Collaborative document management - Tools like Microsoft Sharepoint (and even Wikis) provide predefined repositories where anyone can post content. Assuming such repositories are well designed, SMEs can readily drop in snippets of information. It is much easier to write paragraphs than pages. Depending on the audience and its expectations, that might be all that is required for some documentation needs.

Content management - Tools like Documentum and Madcap Flare (and standards like DITA) go even further in providing pre-chunked information categories. Depending on access to the system, an SME might insert his/her snippets directly into a documentation database. Such systems (at present) handle topic reuse better than collaboration-only tools. They also provide greater flexibility and capability in formatting output.

(Another factor might be the professionalization of tech writing. Many younger writers now have college degrees in technical writing. One suspects that these programs spend more time teaching the management and facilitation of tech writing than the actual writing. That is probably a given.)

Of course, nobody knows really what is happening with black swans. That is why they are black swans.

Even today, while this particular black swan is still flapping its wings, the technical writer is no longer just a writer (not even a 50% writer). For example, I know of a company whose six-person "writing staff" includes three programmers whose job is to maintain an in house content management system that automatically moves the comments of other programmers into external documentation.

Who knows what it will be like when this bird finds a roost.

Final Historical Notes: Such job altering black swans are not new. Consider the law copy clerk (as in Bartleby the Scrivener). He was replaced by typists and carbon paper. Or consider the archer. A skilled archer could launch more deadly projectiles more accurately than a mediocre musketeer. However, training musketeers was cheaper and faster. Economics overwhelmed classical martial arts. The list goes on and on.

A Wonderful Life

2009-02-08T10:11:00.007-05:00

Found this in a pile of memorabilia. It's for the tech writing job I got at Burroughs in Feb/March of 1978. Salary 14K.

What if I hadn't seen the ad? (It probably ran in the Sunday Observer.) Would I have stayed with my dad building houses - maybe never going back into writing? Would Wolpert have come if I had not already been in the writing group? Would he have even heard about the job? What would have happened to all those connections all those threads?

What if I had never known Johnny. I told him about the job that brought him back from Florida? Would he have come back? What would have happened to Richard if I had never told him about job that seemed to push him over the edge into suicide?

Weird.

Tech Writing in a Flat World

2009-01-25T19:19:00.012-05:00

“Flat world”, as defined by pundit Thomas Freidman, refers to a world that has been leveled by ten great flattening forces, where work can just as easily done there (or so the story goes) as here. See my Book Report, The World is Flat, for more on this.

Last year I blew off two jobs (probably wouldn’t do that now) for various good and not-so-good reasons. One thing the jobs had in common (besides the absence of me) was that they both involved tech writing in a flat world.

I thought about that after attending a recent “writer’s lunch” during which the subject of offshoring tech writing came up. The consensus was that offshoring is not practical – that quality and management issues will always kill it. Here are some arguments:

Unless a writer has grown up speaking and writing American-style English, he or she will not be able to convey the nuances of American-style content.
People who did not have English as their first language will be more likely to make the language-related category mistakes discussed in Writers Who Couldn't Write .
The time and distance problems of offshoring are just too great.
Writing is impossible to quantify – it is inherently fuzzy.

I want to agree, but those two jobs make me wonder.

One place (Company L) already offshores some tech writing. They have four writers in Jordan (the homeland of a company founder) and four writers in Charlotte. The Jordanian writers document code written by Jordanian developers. This has been going on for years and apparently works.

Of course, you could argue that Company L is a special case. The fact that Jordan is the homeland of a company founder would certainly inspire folks to make the process succeed. Plus, the products being documented are so highly technical and specialized that ordinary writing requirements might not apply.

Maybe.

The other place (Company JD) seems more hopeful. The company does not now offshore writing – although their products are known and sold world wide. They told me that they would never offshore any writing that involves composition, e.g., “real” writing. They say they only offshore mechanical tasks, such as the creation of parts lists.

However, Company JD is pursuing structured authoring with real vigor – has been for years. And they are very keen on keeping the bottom line low. So I wonder.

As more and more content gets turned into manageable chunks in a database, the management of that content will become more and more important. Also, as the chunks get smaller less “real writing” will be required. It takes less composition skill to create a paragraph than a page. The management of content might be viewed as the real creative process. Creation of content might be viewed as a mechanical task. Will a time come when LH (the boss) says, “Oh fudge, let’s send the stuff to Bangalore.”? Will LH be able to resist being able to reduce writing labor costs by a half or more– especially in this economy? I doubt it.

Someone like LH (or Thomas Friedman) might argue, “In a flat world there is no longer any such thing as American-style content. Products that are used all over the world can be documented by writers from all over the world. Further, if the documentation is going to end up being translated into multiple languages, then you don’t really want to start out with English in any particular style, American or otherwise – some neutral English learned as a second language might actually be better for translation.”

Anyway, it does make you wonder.

Note: Obviously, a lot of work can’t be offshored. No disorganized little company in the early stages of entrepreneurship is likely to send its documentation offsite. The same is true for disorganized groups in large companies. In such places, it’s hard enough for writers in the same building as development to figure out what is going on. Writers on the other side of the world would not stand a chance. Friedman includes such physically anchored workers among the “untouchables” – people whose jobs can’t be sent overseas. More on this in another post.

Black Swan in Corner of Room

2009-01-24T17:20:00.000-05:00

According to trader and philosopher Nassim Taleb, the unseen creature in the corner of the room is not an elephant, or an ape, or a 900-lb canary. It is a Black Swan. Taleb, the author of The Black Swan: The Impact of the Highly Improbable, says that Black Swans are unexpected events with significant impact that appear, after the fact, explainable and predictable. Because of our built-in human need to see the world as orderly, we tend to ignore Black Swans. But, the truth is they are everywhere, ready to render moot and meaningless all our plans and predictions.

We are all covered in Black Swan poop.

Here are two true stories, and an obvious observation (in which I note that the generally hopeful, cheerful, energetic, positive, and sincere people who run projects cannot believe in Black Swans).

First True Story

Ever since supervising 14 writers at Burroughs in 1979, I’ve bragged about how we never missed a deadline. Depending on the audience (and whether I am trying to get a job, or just telling an outrageous story) I might mention poor Richard Smirthwaite’s book. That was the 80 page, 8-by-10 document which we updated with over 100 pages of 10-by-14, green-bar computer paper. Not having time to retype the manual (that’s how we did it then) we inserted the green bar paper between the pages of the existing documents, leaving the longer paper flopping off to one side. I don’t recall if any documents actually went to customers like that, but the point was, we made the deadline.

Usually when bragging about these experiences to get a job (and leaving out the part about Poor Richard’s book), I imply that the reason we didn’t miss any deadlines was because we did better planning. And it is true that I spent more time than others making lists and charts. However, even though the doc group might have had a better idea about the status of our projects, the reason we didn’t miss deadlines was because we either worked overtime or cut corners.

Our planning was no better than anybody else’s. We were all susceptible to Black Swans.

Poor Richard’s Black Swan was the appearance of unexpected business requirements. Of course we should have seen it coming and planned accordingly. But that’s how Black Swans work. After the fact they become inevitable and obvious. Before the fact they are invisible.

We overcame this Black Swan by sacrificing quality. Sometimes, that’s how deadlines get met (and how Black Swans get wrestled to the ground by existentially perky project managers – which is what I was trying to be back then).

Second True Story

(Where quality was not sacrificed but failure happened anyway).

From 1998 to 2002 I worked as a Senior Business Analyst for Acme Corp (not the real name), a little company supplying tools and applications to the banking industry. At that time we were developing Business Portal, a collection of web-based applications and management tools. My job was gathering requirements for the Administrative channel.

Although none of us knew the term “Black Swan”, we had all been around. We had seen projects go awry because of unexpected events. However, most of us still believed that successful projects were possible if everybody - the managers, project leaders, architects, programmers, writers, and analysts just took their time and planned for everything.

Such an approach had several effects, all of them unexpected.

First was a prolonged period of “analysis paralysis”. Because everyone was afraid of getting the design wrong, nobody could agree on anything. We spent weeks and months fighting about basic architecture. Company management finally forced a decision, although by this time, the new technology on which our architecture was based was no longer new.

The second effect was the time it took to get specifications written. Still afraid that we would get something wrong, or miss something, design sessions were lengthy and contentious. Everyone stayed upset. Programmers resented detailed specifications that restricted their creativity, yet became angry if something was left out. As author of the specifications, I resented being resented.

In addition to these procedural Black Swans, there were also unexpected stumbling blocks resulting from off-the-cuff technical decisions. I don’t recall now exactly what these decisions were, although I do know that they were made with the best of intentions. For example, one day, standing in the hallway casually talking with a senior developer, the system architect decided that things would be better done this way instead of that way. It seemed a minor thing at the time, but as the programmers got into the revision, it was discovered that the entire system had to be reviewed. A month or more was added to the schedule. In another case, the senior web developer decided the system would look better with a new design. He was right, but the result was another delay in the schedule.

Months and then years passed. However, in spite of all the Black Swans, work did proceed and a quality product did emerge. The window of opportunity for selling the system was closing, but in the Fall of 2001, a potential customer had emerged, a big bank that would become the positive Black Swan to offset the previous negative Black Swans. The day finally arrived when all our executives and senior staff were to get on a plane and fly to Chicago to close the deal. Success, although not certain, seemed possible.

That day was 9/11/2001 – the day a very large Black Swan excreted over the entire world. Our flight was cancelled; the deal ultimately feel through, and within a year almost everyone was gone, leaving behind what many of us regarded as the best system we never completed.

Obvious Observation

Smart people have proposed various methodologies to address the problem of the unexpected (Black Swan). In the software world, these methodologies include the Rational Unified Process (RUP) and various forms of Extreme and Agile programming. All of these systems are based to one degree or another on the notion of iteration – meaning you get a chance to redo the plan when things (Black Swans) happen. These systems are contrasted with “waterfall” processes – meaning you do tasks in a prescribed order and don’t get a chance to redo the plan. If things happen, well, you slide, dance, glide and/or lie as long as you can then commit quality control seppuku (recall Poor Richard’s book) when nothing else works.

My obvious observation is that none of this matters. Anyone who has been around knows that people who run things do not believe in Black Swans – at least not the negative kind. It doesn’t matter what they say or what methodology is in place. They do not - cannot - believe that bad things will happen. That’s because bosses must remain hopeful, no matter what. Optimism is their business. The possibility of failure cannot be admitted and once having happened must be ignored or blamed on somebody else. Even the manger of an Agile programming team will demand a project completion date. And when unexpected events (Black Swans) cause the date to slip, the manager, who should know better, will still blame team members.

And what’s even stranger, the most conscientious members of a team in which a delay has occurred will feel guilty, as if it is somehow their fault. They will take responsibility for events over which they have no control. It is from this pool of guilty workers that future managers emerge.

People who do believe in Black Swans hardly ever get into management (or if they do, must become existentially perky, at least until they crack under the strain).

Although some people who do believe in Black Swans are snarky and surly, many are placid and ordinary - if not existentially perky, then at least existentially polite. They know the score but come to work anyway, because for them the work is often enough.

Some of these people are technical writers - the existentially polite, the existentially interested. the inadvertent Zen masters - the hobbits, the halflings of the technical world.

Ancient Art

2009-01-03T14:22:00.021-05:00

"Art", circa 1979, from the near-mythical Burroughs Documentation Group.

The art consists of sketches and drawings that reflect the interests and psychoses of the group in general, and Paul, Richard, and me in particular. Themes include the group itself, system software, odd animals, how to eat Bar B Que sandwiches, gastrointestinal distress, and the characters of Mr. Foetor and Mr.Pus.

Aside

The Burroughs/Unisys Documentation Group was located in Charlotte NC, first in the old Merchandise Mart then in the Rexford Rd building near South Park mall. Karen came from California in 1977 to hire the first writers then escaped back to those sunny shores in 1980. The group endured until 1990 when just about everybody got laid off. (In an odd twist of fate, the laid-off writers went to lunch that last day at some Mexican place in the Park Road Shopping Center where I happened to go on my first day at Network Controls. I wondered why everyone seemed so sad sitting there at the long table.)

In addition to this art and ten feet of real Burroughs documents (one of which even won an STC award), the group produced a manual for eating Moon Pies, short stories written during "writing to sell" sessions, and the "Briar Creek Sagas".

My other Burroughs-related posts are listed below:

Extracurricular Writing at Burroughs in 1979
Cursors and Menus
Last One to See Jones
Lunch Walks
Writers Who Couldn’t Write (Excoriation, Stobbing,...
Black Swan in Corner of Room

Tech Writers and Hobbits

2008-10-12T17:20:00.010-04:00

Are technical writers like hobbits?

Consider this…

Tech writers and hobbits really enjoy eating. (Well, some tech writers anyway.) At one of my recent gigs, before the current economic embarrassment, there was a lot of free food - regular company lunches and breakfasts, and leftovers from training classes and executive meetings. The writers, who sat in a communal office, had spies all over the facility who emailed alerts whenever food showed up. Then the writers would casually wander over to wherever the free food was located and grab up their share. Most Fridays, I worked with a fancy pastry positioned conveniently beside my keyboard, allowing me to nibble my way through the day. I gained 10 pounds that way.

Tech writers and hobbits are relatively small. You say that you have known big tech writers? True. Physically I am not small (see previous paragraph). However, organizationally, tech writers are halflings. If personnel charts showed people in proportion to their perceived value, tech writers would be smaller than engineers, salespeople, project managers, etc.

Tech writers and hobbits appreciate a good hole or warren. A tech writer spends so much time in his or her workspace that making it livable becomes important. And no matter how bad the current situation is, a tech writer has probably seen worse. Click When a Tech Writer Leaves a Pretty Good Gig to read about the little things that one tech writer liked about her recent situation (before the job went to Mordor).

Tech writers, like hobbits, usually appreciate one another’s company. For example, tech writers at the free-food organization mentioned above occupied cramped, back-to-back work stations in a long communal office. However, when given the opportunity to move into regular cubes, most preferred to stay in the “writer’s room”. That was because they enjoyed being near other writers. It was cozy. And the stories were first rate.

Finally, like Bilbo and Frodo, some tech writers support a “Ring of Power”. The Ring in our case is documentation. Without documentation, some companies would not know what they have. I have been in a number of places where the tech writers explained software products to their creators. The developers knew the bits and pieces but not the whole picture. At Burroughs in 1979, no developer knew how the Burroughs Hospital Information System (BHIS) really fit together until John Yankech wrote the BHIS Environmental Manual. And like Bilbo and Frodo, we aren’t always loved for what we do. The best people appreciate and value us. But the worst resent our power – seeing us as taking over their stuff.

When a Tech Writer Leaves a Pretty Good Gig

2008-10-09T12:21:00.001-04:00

She wrote…

I love this building, where I park, and the cubicle where I sit. My cube is at the end, farthest from the window, which means supposedly it is the least desirable. But all I have to do is stand up and take two steps, and I’m at the printer. It’s really quiet on my row (the rest of my team, including Fred, is on the next row). The cube is fairly large. The AC works pretty well here.

I love getting here at 7:15 - 7:30 AM. There are not a whole lot of people here then. Sometimes I see Skyler in the little break room. He is my boss’s boss’s boss; he’s the guy who said “How in the world did you write all that?” He’s the one I was terrified of until he saw that I’m good at what I do, the one who asked me about working on documentation governance, etc.

Then there’s Don, who sits on the next row over. He’s on the end, too, so there’s just a wall between us. We both get here early. He’s sort of like you. He’s very technical and does mostly technical analysis work, but he is also a writer. He’s the one who set up most of the WIKIs here, and he’s a SharePoint wiz.

Well, I will miss a lot about this place - even the terrible free coffee.

One of the people I will miss the most is the security guard who opens the door for me whenever she sees me coming. I love her. She’s friendly and down-to-earth. She says “Yes mam” to me, and I think it’s wonderful. I would like to give her a little thank you note with some money in it tomorrow. I’m debating about whether to do it. I’ve got to start watching my pennies now, but it would give me great pleasure to hand her an envelope with about $20 and to say “Thank you for always starting my day off with a smile and a friendly greeting”.

Well, we’ll see.

Writers Who Couldn’t Write (Excoriation, Stobbing, and Category Mistakes)

2008-09-08T09:32:00.020-04:00

Excoriation

It was 1980. We were conducting an exit interview at Burroughs on the fourth floor of the old Charlotte Merchandise Mart (not far from Briar Creek, where elderly people fished for crappie off the little pedestrian bridge, and next door to my office where Jones showed up the last time before disappearing into legend).

Johnny, the Documentation Manager, sat behind the desk and smiled sympathetically. He looked like John Denver, but more ironic. As the Writing Supervisor, I sat beside the woman and expressed concern by steepling my fingers under my chin. I’ve been told that I looked crazy back then. I was probably smoking.

The woman said something like, “You are non-professional and vulgar. You are never serious and you turn everything into a joke. You are very depressing. That is why I am leaving. You are making me negative.”

She closed by noting, “And you are smug, although I don’t know what you’ve got to be smug about.”

Johnny told her, “I’m sorry you feel that way. You are wise to leave.”

I offered, “Well, good luck.”

Except for the non-professional part, she was probably correct in everything she said.

What she didn’t get, what most of the other writers did get, was that we were very serious about the work. We cared about the writing.

I don’t remember if this woman could write. It is certainly possible that a qualified writer could have been disgusted by our antics. Having become old and cranky, I probably could not tolerate now the group that I so admired then. Perhaps the woman has since won awards and managed large documentation groups.

However, I’ll bet she was one of the four or five people who stayed for a while and then, to everyone’s relief, quit. They were the writers who couldn’t write – or at least couldn’t do technical writing, which is all we cared about.

Two of our most important criteria for prospective technical writers (aside from not being prima donnas and not overtly hating computers) were the ability to:

Stob
Perceive category mistakes

Stobbing

“Stobbing” is a southern construction term. I picked it up in the 70's when working as a house builder for my father (when I wasn't underemployed as a textbook author or instructional designer). Some of my fellow writers thought it sounded funny.

Stobbing is what you do when you start a house. “Stobs” (2 x 4 stakes) are driven into the ground at each corner of the structure. Batterboards are nailed to the stakes and strings are drawn between the boards to show where the foundation walls will go.

Stobbing is the first step in transferring an abstraction, the blueprint, into physical reality. Depending on the nature of the dirt (sometimes red clay baked rock hard by the sun) and on the complexity of the structure (sometimes interconnected shapes resembling a Mondrian painting) stobbing can be very difficult. Not all carpenters can do it. A good stobber must be able to see how patterns on paper translate into lines on the ground and how those lines translate into a house.

The analogy with technical writing is obvious. Like a good stobber, a good technical writer needs to be able to translate abstractions into physical reality. The writer needs to see patterns in abstractions and represent those patterns in the structure of a document. That is what it means to stob (or design) a document – recognizing patterns and creating informational foundations.

Of course, document-level pattern finding has never been an absolute requirement for all technical writers. In established departments, like ours back then, much of the work involves maintaining documents that have already been designed. Some writers, especially the new ones, don’t have the pattern finding ability at first, but eventually learn how to do it. Some writers never learn. (Some writers take course in Information Mapping and DITA.)

However, stobbing or pattern finding also takes place at lower levels. Parts of speech are related by rules or patterns. Patterns connect sentences in paragraphs and paragraphs in topics. Being able to perform various writing techniques derives from an ability to handle word patterns. Consider parallel construction – that’s an exercise in small-scale patterning. Or regard the old dialectical trick (thesis, antithesis, synthesis) of structuring information. That is stobbing with a Hegelian flavor. Order and predictability come from patterns (dramatic interest comes from breaking patterns in artistic ways).

So, whenever possible, we hired stobbers.

Category Mistakes

Gilbert Ryle employed the term “category mistake” in The Concept of Mind, which several of us had been forced to read in college philosophy courses. A key point of the book is that mind and matter are logically different concepts. You shouldn’t use mind terms when talking about matter and vice versa. That would be a category mistake.

An example is the sentence, “Mind is located in the brain.” It is syntactically correct but categorically incorrect. The word “located” means something physical. Mind is not physical. A more correct sentence might be, “Mind is implemented by the brain.” Or, “Mind is an epiphenomenon of the brain.”

As before, analogies with technical writing – especially computer documentation, are obvious. A competent technical writer would know that something is wrong with the sentence, “The function is located in the computer.”– that it would be better to say, “The function is performed by the computer.” (Unless, of course, one were working for a chip maker who defines “function” as a set of physical switches and gates.)

These kinds of category mistakes are the result of ignorance. When I started at Burroughs in 1978 I did not know the meaning of the word “menu” in the context of computer software. I made a variety of category mistakes before figuring that out what that meant.

Every writer occasionally makes ignorant category mistakes. It depends on the job and how deeply you are in over your head. For instance, someone who has only written end-user software documentation might be expected to make category mistakes when doing an architecture document.

At Burroughs in 1980 we were not too concerned about the ability of prospective writers to spot these kinds of category mistakes. Within the limitations of our own ignorance, it was a skill we were prepared to teach.

Of more concern was another, deeper level of category mistake involving not just computer literacy but basic word literacy.

Ryle illustrated this kind of category mistake with the sentence, “She came home in a flood of tears and a sedan-chair.” It is an illogical (or as Ryle would say an absurd) conjoining of emotional (flood of tears) and physical (sedan chair) terms.

Good technical writers instinctively recognize (and enjoy) these sorts of category mistakes. Any writer who has been in this business more than a few years has received an emailed list of the latest examples of such mistakes which he or she immediately forwarded to the next group of writers.

Bad technical writers don’t get it. They don’t see the illogic and the absurdity.

Sarah Margaret Aside

Category mistakes that rise (or descend) to the level of art are contained in Letter From Sarah Margaret, one of my Dairy Queen Nights stories. Here is an excerpt:

Dear Franklin and Margaret,

Thought I would write you a few lines.

I talked to Lillian last night and she said Grandpa Hyndman was a Shoemaker.

Suzanne is cleaning up my house getting ready for Danny. She took the curtains down and washed everything on the beds. I have 3 bedrooms.

Suzanne brought me 2 hot dogs up last night. She will be going to the church tonight. She is going to have hamburgers tonight and chicken tomorrow night.

Richard’s daughter has 2 jobs. He has gone to feed the cattle.

The girl that cooks for one of his friends sent steak, potatoes, corn and brocklic and carrots over here Sunday night. He eat supper with him. His wife left him.

Lillian had her mouth operated on. She can’t wear her lower teeth.

Doug’s insurance didn’t pay for Suzanne’s hand. She works every day. You can see yourself in her floors.

We put in 3 pumps. They worked here all day last Sat. Suzanne bought the pipe. They hooked me on to Ronnie. I’ve got more water pressure than I ever had.

It’s about time for the mail, so I guess I had better close. Tell Franklin to write me.

Love,

Sarah Margaret

Although wonderfully connected on a deep, Faulknerian level, at the structured level where most technical writers live, these sentences are a maddening mix of categorical issues. As an editor, what would you do with “Richard’s daughter has 2 jobs. He has gone to feed the cattle.”? How could you make sense of that without doing a total rewrite? It would drive you crazy.

It isn’t only the writing but the thinking. You just know that Sarah Margaret sees the world differently than the rest of us. For her everything is part of a unified whole – ineffable and indivisible, not to be neatly categorized. Sarah Margaret is a Zen master who doesn’t know the word Zen. How would you explain cause and effect, this versus that, to a mind that already sees connections in everything? It would drive a stobber crazy.

This is what we were trying to avoid, being driven crazy by people who couldn’t stob and who committed category mistakes on our level (but who might be geniuses and poets at another level).

I suppose we were successful.

Ghosts on Morehead Street

2008-08-16T07:34:00.005-04:00

Morehead Street Y, Charlotte NC

The Cardinal building on Morehead Street is long gone, the ground cut away for a ramp onto I277. (We got the place cheap knowing that the interstate was coming. It’s just air now.)

The old YMCA where we ate lunch and afterwards played ping pong and snooker has been gentrified and sanitized. People like Howard the Hand Model no longer live upstairs. The blind masseurs in their white uniforms, referred to by Jones as eyeless newts, don’t venture forth every morning from city buses to ply their trade at the Y. They have been sent home for good.

Toward town, half-million dollar condos intrude on the sidewalk. Conders’ Sundries, where we used to go for afternoon beer and pork rinds has become a yuppie place.

For all practical purposes everything is gone. But maybe for all impractical purposes it is not. Maybe we left ghosts - uneasy psychic husks that linger along that stretch of road, haunting the occasional passerby.

Imagine this.

A bright young man walks by the remnants of the empty lot where we played horseshoes. He gets a sudden whiff of cigarette smoke. It doesn’t smell half bad. Looking around, he sees nothing, but hears the echoes of distant laughter and the faint clanging of iron on iron. A voice exclaims, “Fucking A, man.”

An intent young woman jogs past our vanished front door. She feels a hand lightly brush her sweaty well-shaped ass. Whirling around, ready to press the button on the canister of pepper spray hidden in her right hand, she sees nothing. But she smells a feral, animal odor and hears a deep gravely voice whisper, “Hello, my dear.”

An older man (a banker) strides confidently past the empty air where Big Daddy used to scheme. The man wears an expensive suit. Out of the gathering dark, a rich baritone voice announces.

“One million dollars.”

It sounds like the evening news. But there are no cars nearby, no residences where a TV or radio might be playing. The banker assumes it is the fall air playing tricks.

The voice continues, closer, more personal, “They say you aren’t really a success if you don’t owe a million dollars.” The voice laughs. “Well, by that measure I am a success.”

An invisible hand clutches the banker’s shoulder. The voice comes now from inside, like an incipient heart attack. “Harumph. I say friend. You wouldn’t be interested in an investment, would you?”

The banker imagines a face, wattles red and tremulous, eyes ironic and all seeing.

Another young man (a technical writer) stumbles over a psychic irregularity in the sidewalk where our driveway used to be. He looks up at the exact point in space where 35 years before another young technical writer stood at his office window, arms outstretched in a crucified pose. Looking down on Morehead, the writer from times gone by imagines that he is somewhere else. Both men are filled with nostalgia, one for a time that never was and the other for a time that will never be.

Link to Cardinal Acid Trips

2008-08-05T10:37:00.003-04:00

Wm P posted this on Strange Room.

(I too saw the rat fall omen-like from the sky, dropped by an anxious buzzard to strike the windshield of our careening bird wagon.)

Travels with Big Daddy and Other Adventures

2008-08-02T13:06:00.008-04:00

Great Blizzard of 1978, Ohio

Not only was Cardinal fueled by alcohol and cannabis, there was gasoline and jet fuel. We scoured the country seeking customers for the Directed Action Response Training (DART) system of machine-based training.

(We offered a 90/90 guarantee. If 90% of a client’s students didn’t achieve 90% of the training objectives we weren’t owed any money. I never could understand why more customers didn’t jump at this. Some simply didn’t understand. This was frustrating, and might been the reason that O. Donald, on one of our visits to Dayco Corp in Dayton, when dealing with a particularly dense and argumentative executive, leaned back from the conference table and sternly announced, “I will not engage in a pissing contest.”)

During the early years, initial contacts were usually made by Big Daddy CEO (Wm P’s name for him) or his lieutenant, O. Donald. If the deal looked promising, the principal would return with a senior producer, somebody like Wm P or me. During the middle years, when there was money, salespeople often made initial calls. (During the final years, Big Daddy and K traveled in a motor home to cut expenses. K told me that they performed a preflight checklist every morning before heading out and usually got drunk in the evening after the day’s business was done.)

Perhaps the most famous Cardinal traveler was the salesman Carl B. I never saw him but heard that he was a distinguished-looking middle-age man, a hard drinker, but no different from his co-workers in that respect. Supplied with a DART kit, an expense account and a “bird” wagon (a 1973 Chevrolet station wagon with a picture of a Cardinal on the side), he was sent to find business in the middle part of the country. That didn’t work out. Instead of performing his assigned role, Carl re-enacted the last days of Willy Loman. I never heard the details – just rumors of unpaid bills, customers not contacted, equipment lost or never returned. My impression was of a sad, drunken man haunting the Great Heartland of America, running from fate, Big Daddy, or something.

In the spirit of Carl B., here are some my Cardinal travel stories.

On my second day with the company, sometime in 1971, I flew with Big Daddy to Chicago to visit Sun Electric, a large manufacturer of automotive test equipment. I was supposed to talk to the technical people while Big Daddy regaled the executives.

On the trip up, I was the recipient of Big Daddy’s attention. Wattles red and tremulous, heavy lidded eyes drilling into my already shaky sense of self-worth, he told me what had happened so far at Sun. He also told stories about his own experiences as a flyer in WWII. I was nervous and every half hour or so made a toilet trip down the long aisle of the Eastern Airlines jet. Just before we landed, when I returned from my last trip to the head, Big Daddy leaned over and said to me, “Harumph. By the way son, you don’t have a kidney disorder, do you? Ha ha.”

Big Daddy left the next morning, instructing me to stay for a few more days. One of my tasks was to pick up a part from a company located in a wholesale district. As I recall the part was not available. Walking back to my waiting cab, I was approached by a man who stuck out his hand and asked me the time. I took his hand and answered his question. The cab driver, seeing this in his rear view mirror, told me that I was stupid – that I needed to forget my southern ways.

The last night in Chicago, I dreamed that Big Daddy had absorbed me, that I no longer existed in my own right.

(At various times I told my father that he reminded me of Big Daddy and Big Daddy that he reminded me of my father. Both thought it was a compliment.)

Typical of our travels in the middle years was the trip to Control Data in St Paul. Representing Cardinal was Big Daddy, O Donald, and me. My role was to observe and ask technical questions. Like all Big Daddy trips, this visit had two purposes: to convince the company to use DART training programs and to demonstrate the brilliance of the DART concept (and its creator).

One scene from the Control Data trip sticks in my mind. We were sitting on chairs and beds in Big Daddy’s hotel room. It was at night. There was a half-empty bottle on a table. Our reflections, animated one minute, torpid the next, appeared on the window. Faintly visible beyond our blurred images was the Control Data facility itself. I don’t remember what we said, except that it had to do with grand plans for getting Control Data’s business. As I recall, the conversation seemed to focus more on us and less on them.

My final Cardinal-related trip was to Dayco (after O. Donald cleared the air with his refusal to participate in a pissing contest they became one of our best customers). It was in 1978. By then Cardinal had died and been reborn as Phoenix Enterprises (Big Daddy might have been dead too; I don’t remember). Because I had been one of the last Cardinal producers on the project (and because I was available), Dayco asked me to come up and talk about doing updates on previously developed material.

I arrived in Dayton on Sunday, January 22. We had meetings on Monday and Tuesday. On Wednesday we were supposed to have a wrap-up session before I flew back to Charlotte. That did not happen. Tuesday night, as I lay in my hotel bed listening to the wind rattle the plate glass window that overlooked downtown Dayton, the Great Blizzard of 1978 roared through Ohio.

For the next three days the town and most of the region was shut down. It is still regarded as the worst blizzard to ever hit that area. Fifty one people died in Ohio. Aside from being trapped in the hotel, my adventure was pretty tame. At one point, when food ran low and the wait staff could not get in, the guests filed through the kitchen to be served big hamburger patties cooked by the hotel management. That was fun and the sandwiches were free.

I managed to escape before dawn on Friday with two businessmen from Philly and Pittsburgh. Sliding over icy streets at 60 MPH in a cab driven by a man who had been up for 24 hours we managed to get to the airport and on the first plane to leave Dayton. Going down the icy runway, the cabin still chilly, we watched with tiny faces as snow swirled past our rushing windows.

I never saw anyone from Dayco again. The momentum had been lost and four weeks later I got a regular job as a technical writer for Burroughs and Cardinal receded even further into the mist.

Extracurricular Writing at Burroughs in 1979

2008-07-18T13:59:00.004-04:00

There are three kinds of technical writers, those who see themselves as writers first and technical people second, those who see themselves the other way around, and those who aren’t sure.

Most of the 13 technical writers who worked for Burroughs in 1979 on the top floor of the Charlotte Merchandise Mart belonged to the first group, at least initially. We regarded ourselves as writers who were doing computer documentation just to make a living. The concentration of artistically inclined tech writers was partly because Karen, who started the department, preferred those kinds of people. Also, they were cheaper. The Burroughs philosophy was to hire people who could write and teach them about computers.

It was inevitable that some of those writers dreamed (at one time anyway) of selling stories.

I know that Mr. Seed wanted to write science fiction like Philip K. Dick.

Thomas Treplow joked about living in a cheap trailer in South Florida and writing pulp detective stories. Thomas was so enamored of the noir life style that he referred to Sarah, who reminded him of a femme fatale in a 1948 movie, as “toots”. She called him, “tootsie”. They became friends and at one time even jointly owned a rental house in Sedgefield, between South Blvd and Park Road.

I wanted to become a Southern Writer living in Greenwich Village where I would author the Great American Novel. But I would have settled for selling any kind of fiction. By that time I was close to publishing the first of several technical textbooks but they were never the same as novels.

The women, who were better grounded than most of the men, never talked about such fantasies. However I expect that among Karen, Canda, Little Sue, Sarah, Bille, Sybil, and Mellisa there were several Flannery O’Connors and Carson McCullers.

This shared interest in artistic expression resulted in numerous extracurricular group writing activities. Over the years, they included The Briar Creek Saga, The Writing to Sell Sessions, The Job Application of Melinda Dawn Roberts, and The Moon Pie Handbook. Because this article is restricted to events taking place in the Merchandise Mart in 1979, I’ll stick with the first three activities. (Anyway, the people who came later are better qualified to write about the Handbook.)

The Briar Creek Saga was a collection of collaborative stories about the adventures of a madcap group of boys and girls along the mythical Briar Creek. The real Briar Creek meandered nearby. We sometimes crossed it on our two-hour lunchtime walks, speaking to the old black men and women who fished for crappie off the little bridge.

The idea behind the Saga was that somebody would write an episode, setting up a situation which somebody would follow with another semi-related episode, which somebody else would follow with another episode, and so on. The entries were supposed to anonymous; stuff was just supposed to appear in the Saga notebook which was kept by the coffee pot. However, everybody knew who did what.

People knew that Treplow and I wrote the dueling scatological stories. (I remember writing the word, “blorp”.) People knew that Smirthwoo wrote the piece set in an Eden-like glen in which his character danced half-naked by firelight in front of a group of amazed and appreciative females. And people knew that Little Sue created the demure girl who appeared in a wrap-around leather skirt before a dirty old man and “whipped off the skirt and said, ‘what do you think about that big boy!’”. Karen might have shut down the Sagas after Little Sue’s contribution.

The Writing to Sell Sessions were also exercises in creative writing. At 11:00 AM every Friday, before going out to a group lunch, we wrote for a half an hour on a given topic. Because this was before personal computers and word processors, we used the typewriters that we had brought in from home. The machines ranged from Mr. Seed’s IBM Selectric, to my little blue and white plastic “toy typewriter”. At that point, we were all sitting in one big room so when the Sessions were going it was pretty noisy.

The Session rules said that we were to write fast, without thinking, in a “writing to sell” style – whatever that was. Paper, once placed in a typewriter, was not to be removed until the page was finished. There could be no re-writes, no corrections. I suppose the benefit, from Burroughs’ point-of-view, was that we were learning how to write faster. (Which might have worked because our writing group turned out 25 linear feet of documentation and never missed a deadline.)

Entries were judged at lunch. The best story, as I recall, was the one Treplow wrote about the little female programmer. Until the story was read aloud, even Treplow didn’t realize how vile it was. Taken aback by his own writing powers, Treplow tore up the story and would not talk about it anymore.

The Job Application of Melinda Dawn Roberts was an altogether different sort of project. I never knew who was responsible (nor do I want to know) but I suspect Sarah was the lead, supported by several other women, and perhaps one or two Burroughs’ traveling sales people.

By this time, I was the Writing Supervisor, working for John, the Writing Manager. Melinda Dawn Roberts was supposed to be a woman who wanted to join our group. For a year or so, she sent me letters from up and down the East Coast, expressing her interest in being a technical writer. I don’t recall what she said, but I do remember that she liked “Hard Wear” and once included a poem called “When Hard Wear Becomes Soft Wear”.

I never met Melinda Dawn. She kept promising to stop by Charlotte, but because vague obligations to some football teams took her to Atlanta, Miami and other places, she could never manage a visit. However, she did send a picture with one of her letters. It was of a beautiful, but somewhat dissipated blonde woman sitting by herself at a Formica-top kitchen table. There were several half-empty Vodka and whiskey bottles. Although no clocks were visible, I’d guess the picture was shot at 3:00 AM.

Cursors and Menus

2008-07-18T13:52:00.002-04:00

"Mr. Seed"

In 1978, when Karen hired me to do tech writing at Burroughs, I didn’t know anything about computers. Except for “Mr. Seed”, who started at the same time, none of the new writers knew much. As noted in another post, Burroughs could have gotten experienced people, but preferred to find candidates who could write and teach them the rest. Experienced computer technical writers were expensive then.

For most of us, this was our first real technical writing job. Some had been school teachers, some reporters. At least one had been a librarian. A few, like Tom Treplow and me, had written about other aspects of technology, but not about computers.

In my previous 10 years as a more-or-less professional writer, I had bumped into the subject twice, but had never actually learned anything.

My first exposure to computer cursors and menus was in 1970 when I was a Patent Investigator for the Cryovac Division of W.R. Grace in Duncan S.C.. I wrote patent applications and occasionally went to Washington to do research at the US Patent Office. My boss, who admitted when he hired me that it was an odd thing to do, was a dour mid-westerner who had worked for meat packing plants where he learned to eat horse steaks. Anticipating that the Grace Patent Department might one day have to either use or write about computers, he sent me to an on-site introductory seminar. I think it might have featured the language FORTRAN. Nothing stuck in my head. I had no conceptual framework on which to hang the facts being presented. Also, being the only person in the room without a college degree (a few had PhDs), I was shy about asking the necessarily stupid questions.

My second exposure to computers was after I had left Cryovac to get an English degree and go to work for less money as a writer and producer of instructional materials for Cardinal Associates. In 1972, O. Donald, McGahey, and I took an exploratory trip to Control Data in St. Paul Minn. We were looking into the possibility of developing DART (Directed Action Response Training) programs on how to use Control Data terminals. The night before going on-site, the three of us sat in a hotel room overlooking the huge Control Data facility. We drank alcohol and devised strategies for adapting Control Data to DART (it was never the other way). The next day we toured the facility and listened to the Control Data people try to explain the difference between computers and computer terminals. O. Donald might have picked up some of it, but I didn’t. Neither did McGahey. To cover up, he went into his Big Daddy/Churchillan mode.

It was at this level of ignorance that I showed up in March of 1978, along with Mr. Seed, to write about the Burroughs Hospital Information System (BHIS).

Although I never did develop any deep expertise at Burroughs, I did have few breakthroughs.

I learned what a cursor was. In my first document, the BHIS Overview User Guide, I included a picture of a black square, called a Cursor and explained what it did. In that document I also explained computer “menus”. Because BHIS was used in hospitals and hospitals provided food, I initially thought that “menus” had something to do with cafeteria operation. When I did figure out the difference, I assumed, as writers do, that others would have the same problem. Apparently, for the time, the document wasn’t that far off because it won a prize from the fledging Charlotte STC group.

Writing about application software did not require us to become computer experts. We could view the forms presented on computer terminal screens as analogs for paper documents that got magically processed by a “mainframe” located somewhere else. Learning that a mainframe might be referred to as a “host” and that it could be “invoked” was as deep as most of us got.

John, who was there first (having transferred, at Karen’s request, to Charlotte from a Burroughs center near Philadelphia), was the only one who came close to becoming an expert. He wrote the BHIS Environmental Overview document (or something like that). It combined information in ways that no one, not even the systems people, had thought about. Like other great Catholic scholars from the past, John talked to the experts, researched related documents, and synthesized the results. Each day he tried to develop at least one idea – which some days meant that he wrote no more than a single paragraph. At that point in the day, after documenting his idea, he would announce to the large room where we were all housed, “Great Shit!” From that time on, such hard-core work was known as great shit documentation.

However, I did have one more revelation before leaving in 1981. (I joined Cherry Bekaert & Holland in Gastonia to avoid becoming the Burroughs Documentation Manger. Karen had already gone back to San Jose and John, the current Doc Manager, was getting ready to bail. As the Documentation Supervisor, I was his logical successor. Thomas X, who would eventually take the job, had yet to come down from Philly.)

My revelation was prompted by Mr. Seed’s explanation of how computers worked.

Generally, he was a good explainer. He instructed me on how to say “shiksa” and corrected me when I pronounced the “l” in “salmon”. He also led the typists (most of whom were young black women) in a session on how to say “ask” instead of “ax”. They sat in a semi-circle around him and when he said “ask”, they responded with a chorus of mixed “asks” and “axes”.

Explaining computers to me was more difficult. I was missing a basic insight. I knew in an abstract sense that people told computers what to do but I had no idea what that meant. Trying to find a level low enough for me, Mr. Seed went to the computer terminal that was located beside the department coffee pot (near the slops bucket that Toots dumped on John when he shot her with a rubber band). He wrote a simple BASIC “Hello World” program. It executed on the mainframe and printed on the terminal screen.

Seeing this simple program control the operation of the mighty Burroughs mainframe was my epiphany.People wrote instructions in languages like BASIC. Interpreting those instructions, computers did things, like print “Hello” over and over. This, as I later learned, seemed to be the gist of all computer explanations. The rest was just filling in the blanks.

Last One to See Jones

2008-07-18T13:46:00.001-04:00

I heard second or third hand that Warntz, Wade’s photographer, saw somebody downtown who resembled Jones. But old winos shuffling by with long stringy hair and downcast eyes tend to look alike. Warntz supposedly said that even if it was Jones, he wouldn’t have known what to do. That was in the early 1980’s.

The last time I saw Jones was in 1979. I was working for Burroughs at the Merchandise Mart on Briar Creek. We were within walking range of East Charlotte high society where Jones was living in the walk-in closet of Mark The Beast (a gentle beast, as Jones was always quick to point out).

I had already introduced Jones to my fellow writers. We had been to a couple of lunches and he had dropped by the office a few times. Never sure of my own cool, I bathed in Jones’ unwashed cachet. (It worked out a lot better than the time back at Cardinal when I set him up with Mary, a writer I knew from the English program at UNCC. Although about the same age, 50 or so, each said the other was too old. I now wonder if both knew that Jones was past any kind of normal relationship and for some reason neither wanted to puncture my persistent naiveté by pointing out that obvious fact.)

But this time there were no complaints. Jones performed his naughty professor role, flirting with the young documentation women, offering outrageous comments in a gravelly voice that always seemed to hide something (good or bad, depending on your point-of-view). I probably told everyone about his law and English degrees and that his father had been a judge and that his brother was a state archivist. He might have mentioned, making it sound romantic, how he lived for a year in the basement of the Cardinal building, across from the Morehead street YMCA.

It was about 9:00 AM the last time he showed up. I was sitting in the five-by-seven office I occupied by virtue of being the documentation pseudo supervisor. We were on a public hall so he had no trouble getting in. I might have heard the light footsteps, or smelled the feral odor before seeing the shaggy head poke around my door.

He probably said, “Hey Whup!” (Using the name he gave me back at Cardinal when I was editor of the literary journal, Livermush.)

I probably replied, “Hey Perfesser”, and directed him to the yellow plastic guest chair that Treplow had salvaged from his kitchen – one chair each for him, Johnny and me.

While chain smoking a handful of cigarettes and gulping at least three cups of coffee, heavily laced with sugar and creamer, Jones told me his latest story. Mark, for reasons that weren’t clear, had finally decided to reclaim his walk-in closet. Jones was headed downtown to a homeless shelter. He had not had anything to drink in several weeks, not because he didn’t want to, but because he was out of money. This enforced sobriety might have been the reason that he seemed so sharp and full of energy, despite the way he looked and smelled. However, something else seemed to be going on. It was as if a burden had been lifted from his narrow shoulders. He seemed free.

After a half hour or so, he left. Maybe I told him I had to get back to work. Although it never seriously crossed my mind to take him in, to save him, I did give him ten dollars and most of my cigarettes. Walking with him down the hall to the elevator, I probably said something like, “Take it easy. Be careful. Come back if you need help.” He told me the first thing he was going to do, before going to the shelter, was get some beer.

Opinions differ regarding what happened next.

This is my vision.

Jones is lying under a bridge abutment. He has come here to die. In the evening traffic noise he hears Siegfried's Funeral March from Götterdämmerung. He is attended by three street people, who only know him as the “Perfesser”. One kneels at his head, the other at his feet, eyeing his shoes. The third is a woman, unrecognized as such by her other companions, but known to Jones. She bends over him. He sticks his hand up her grimy shirt, reaching for what remains of her breast. She bats his hand away. He grins and dies. They strip his body and leave him to be consumed by rats and other creatures that he once described as living at the interstices of the city.

Wm P has different view.

Yes, Jones was the wino that Warntz saw. However, Jones’ brother, the archivist, came to the rescue. He took Jones back to Raleigh and against all odds and all logic, the Professor decided to straighten himself out. (It was always within his power.) I’m not clear about the final resolution of this vision, but it could be that Jones went to work for his brother and is still there, a hale and hearty octogenarian daily visiting the bowels of government, living happily ever after. He hardly ever talks about his life in Charlotte and never speaks of us. It is, he says, a time of ghosts.

That is also a nice story.

Lunch Walks

2008-07-18T13:37:00.000-04:00

Although it was my idea to do lunch walks, Karen made them monumental.

It was probably in the late summer of 1979, after my 40^th birthday (when my Documentation coworkers gave me a party featuring black balloons and a two-colander boob cake which I was required to bite sans fork or even hands). Feeling old, I started doing 30 minute laps around the Merchandise Mart parking lot. In previous years I had jogged in my back yard and in-place in the house but seldom on roads where I would be exposed to public scrutiny.

When Karen learned about my walks, she regarded me with a big daring grin and said something like, “Well, let’s do some real hikes.”

Which is what we did.

Two or three days a week, we explored the neighborhoods around that part of East Charlotte. We never walked less than an hour. Some days we ate lunch at one of the restaurants along the way. Often, engrossed in departmental issues, we walked more than three hours.

Today, those walks are like dreams. Only isolated image stand out - a huge Great Dane trotting out to greet us from behind a modest ranch-style house near Myer’s Park, a dark little restaurant on Commonwealth where we eat greasy fish, a shiny Swiss Army knife lying like a jewel in the grass behind the Mint Museum, Karen’s face burning red in the summer heat when we venture onto somebody’s yard to pluck pears that explode with juice, old black people fishing off the little pedestrian bridge over Briar Creek, Karen asking, “Tom, it is the best of all possible worlds, isn’t it?”

Although it was usually just Karen and me, occasionally Thomas Treplow and sometimes Billie joined us. Treplow, maintaining a spirit of independence, never wore walking shoes and usually smoked. Later, after Karen went back to California, Treplow and I continued the walks, and after Burroughs I kept at it.

The images, even those from recent weeks walking outside Camstar around the grounds of the abandoned coliseum, are still dream like. Or, if Einstein is right and time and space are a continuum, it is all still happening.

In which case…

Treplow and I still cross Sharon Road across from South Park to meander through a neighborhood of architecturally diverse houses from the 50’s and 60’s. Treplow, mimicking the accents of his New York Jewish relatives, says that houses with swooping lines are “very modren”.

Working on a contract assignment for Data General (where Wayne, the writer who says, “Little more need be said.” has already gone) I still walk at lunch down a fire lane into the pine woods in that part of the Research Triangle. I can now tolerate being alone and stand for a few minutes listening to the wind rustle the trees. I find an immaculate deer skull which I take back to the office.

Working at Process Systems with John, I still walk around the office park, usually by myself, but sometimes with other people. I eat in a little restaurant hidden down a side road. Sitting at a window overlooking a red clay field that goes out to I77, I am the only patron. To maximize the variety of my walks, I walk behind buildings and through private parking lots, getting to see the new Mercedes trucks being tested at the Freightliner R&D facility. After being operated on for a blocked artery, I walk even more, finding a creek-side path that Royal Insurance required as part of their building deal but which after one year is being washed away. Linda, who sometimes walks with me, jokes about encountering “royals” along the crumbling path.

I am still a contractor for IBM, first in Charlotte then in the Research Triangle. Walking down the long featureless halls and through the woods in and around the Charlotte facility I imagine that I am an expendable extra on an indifferent star ship. In the toilets, I hear old men moan and strain on antiseptic stools. In the Research Triangle, I find paths through woods where no one ever goes and it is as if I am the only person in the world.

Coming back to Charlotte I again spend 11 years at Network Controls and walk everywhere between Woodlawn Road, I77, and South Blvd. I see a muscular pit bull pawing the dirt near a place that makes artificial flowers. In the woods between the railroad and I77, I stumble on a dwelling made from a large blue tarp tied between trees. A tall thin man stares at me as I turn and walk quickly away.

I leave Network Controls for six months to work in downtown Charlotte. Some days, with a friend, I climb the 21 flights of stairs in our building. When I am with her, our talk passes the time. When I am alone, climbing concrete steps past floors that are all the same, I listen to the sound of my breathing. On rainy days, I travel every public path that is accessible from the Overstreet Mall. It is like a tunnel through the bowels of Charlotte’s big banks. Near Starbucks there is a floor so black and shiny that walking over it is like being traversing a pit.

I still work for Schwab, PokerTek, and Camstar. Walking with Steve and Bill through Ballantyne, past a field that awaits construction of more condominiums, we see a huge black dog, like a wolf, hunched on the crest of the hill. We call him Ghost Dog and wonder if he has acquired a taste for rancid old technical writers. When I walk out into the field, the dog stands up and my companions tell me to come back

Pig Genitalia

2008-07-18T13:34:00.001-04:00

Eddie, William P, and I took a gump to an old mica mine down in South Carolina. Jerry might have been along. I think Steve was testing Dart programs with his drug addicts, or maybe he was in Tennessee. I don’t know about Tom Treplow; he wasn’t much for gumps.

GUMP: A trip taken for business purposes, for which the business is sometimes, but not always, peripheral. We got the term from Jay, a fierce little back man with sickle cell anemia who loved Eddie, a big self-professed redneck and Cardinal’s head photographer. The rest of us had no names, but Eddie was always Mistah Eddie, as in “Mistah Eddie, he off on a gump.”

I don’t recall if this gump had a stated purpose, which was probably why O. Donald was displeased. We came back with pictures, but they could never be used. O. Donald wasn’t picky about gumps, but they had to have some semblance of a purpose. He would have probably approved (if I had told him) of my gump to the local Jaguar dealer to shoot an XKE for Disassembly and Assembly of a Wankel Rotary Engine. Eddie only cared about pictures; he would shoot anything (including, when he could, his signature shot).

We rode in somebody’s little car. There was beer. Any Cardinal gump, and much Cardinal work was accompanied by alcohol. For example, shooting Disassembly and Assembly of a Wankel Rotary Engine took two 12 packs. One 12 pack was for the group shooting the disassembly sequence. The other 12 pack was for the group doing the assembly. Claud stood in the middle coordinating the mechanical tasks. Parts removed on the disassembly side of the studio were passed to the assembly side. Eddie drank and roared, calling me a “third shift redneck”, and Howard, the hand model who lived across the street in the Morehead Street Y pointed with smooth fingers where I told him.

The mica mine was a barren landscape of treeless hills (there were a few shrubs and some weeds, but mostly it was loose rock). Somebody, maybe Eddie, had been here before and wanted the rest of us to experience the dramatic desolation. Eddie might have mentioned that it would be a good place to shoot a desert movie.

I don’t remember if we stopped at the pig pen on the way out or coming back. It was small and muddy, with five or ten pigs, just off the side of the road, in the middle of nowhere. The pigs were full grown. Eddie jumped out with the Nikon and started taking pictures. He didn’t just stand there beside the fence and point the camera; he worked the scene, crouching, leaning, looking for a particular angle. When the pigs snorted and turned to look at him, he called them names evidently because he was not interested in that point-of-view (although as it turned out that might have not been altogether true). I don’t actually have a mental image of him in the lot with the pigs, but I do recall a sense of unease among the rest of us, so it’s possible that he climbed in there with them. I also don’t recall if he shot a picture of the pigs reflected in the car’s side mirror, but I expect that he did, because that was his signature.

O. Donald was waiting when we got back. He didn’t buy the gump. I don’t know what he said, but his quiet displeasure could be terrible. We were all contrite, even William P, who was probably the most unpredictable of the regulars. (O. Donald once said he would tolerate any sort of perversion in his workers, but that he required predictability and being on time at staff meetings. Given predictability, he felt that he could control anybody. He also told me that William P was the best writer of us all.)

Eddie showed us the pig pictures a few days later. To this day, I don’t have the words to describe them. They weren’t just pictures of large, loose hanging pig genitalia. They were art shots, some so close you couldn’t tell what you were looking at – just swirling organic curves. They remind me now of the work done by the German who presents flayed and preserved human bodies as art objects.

Interspersed among the genitalia were pictures of the pigs turning to look back at the camera. These photos were wider. In our parlance, they could have been establishing shots, setting the visual context for the tight shots to follow.

Although the pigs themselves didn’t seem especially bothered, something about the juxtaposition of those views (curious heads and flagrant hocks) seemed sad. I always wondered if that’s what Eddie was after, that juxtaposition of states – a sort of porcine yin and yang. But I never said anything because he would have just yelled at me and called me a pretentious third shift redneck.