Context Thread - November 09

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

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...

1. How well do wikis work as collaborative tools?
2. How well do collaborative tools work for producing external documentation?
3. 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

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.