just write click

Bob Glushko blogs at docordie.blogspot.com, great blog name and a fascinating presentation. I liked that he shared and described his semi-retirement as verbalizing his desire to be a beach bum to his wife, but his wife said, I still like my job and I want to work, so go get a job! He has been teaching at UC Berkley ever since.

Building information supply chains - example of the E. Coli scare in lettuce in March 2007. Basically had to figure out how to track heads of lettuce, similar to tracking heads of people to avoid long lines at security in the airport. With enough data tracking - input and retrievability - you can make informed decisions.

Common themes of new information services - document exchange, patterns, similar to supply chains and distribution channels. There are hidden documents in business processes.

His “ah-ha” moment? he had always focused on the document, but with ordering on the web, his user experience is what really matters - did the business process work? Did the lobsters arrive dead or alive? Did his shipment get to him in time and was it the right order? You have to know the back-end, the time difference, the travel distance, the choreography and design of the pattern determines success and a happy user experience.

I’m reminded of the fact that there are 39 time zones in the world, and for collaboration across the world, we have to figure out the time zone difference relative to the person you want to collaborate with.

Bob offers an excellent analogy for wiki-based, community-collaborative content - a restaurant’s lines of visibility. At McDonalds, you have backstage production lines for food prep, at Benihana you have food prep as part of the entertainment right at your table (remeber that onion volcano so expertly prepared?) We should try to strategically determine where to draw our lines of visibility - what point of view do we wish to present to our users?

Ah, now he’s talking about a cooking school where the kitchen is the front stage for the cooks, and the back stage for the customers. A restaurant’s dining room is the front stage for the customers, but the back stage for the cooks. I’m reminded of a webpage I read where people proved that writing on a wiki actually helps you learn more about the tasks because you have to figure out your conceptual understanding of the task to write about it. If you allow more writing to happen next to the backstage when it’s the cooks in the kitchen, or the expert writers in the wiki, more beginners can learn by not observing or reading but by actually participating in the writing itself.

While you may have identified more with either the front end or back end design issues, you can choreograph the information experience for the user.
Here are Bob’s slides, also found on slideshare.net.

South by Southwest Interactive is a big web design/blogging conference in downtown Austin. There are thousands of people here for it in 2008. It’s crazy busy.

The latest excitement was in a friend’s panel where people tried to stage an uprising on both Twitter and in the meebo room at meebo.com/sxsw, set up specifically for this talk. Tom Parish has a great picture and is quoted in this Wired blog story. The very next day, the Zuckerburg interview had a similar uprising on a much grander scale. Jeff Jarvis has the best analyses I’ve read so far about it, and Scoble’s view from the Twitter gallery is also a good read.

I’m of two minds about the things that have happened here this week - on one hand, I think the conference is only as high quality as its presenters. If all the attendees think they’re smarter than and better than the panelists, then why bother coming at all when you can view the video online or listen to the podcast later? I guess that hypothetical question is answered with - we come because we can interact with the panelists.

I even witnessed a panelist admit that he “wasn’t paying attention” to another panelist’s answer to a question during their panel. It came across as immature, arrogant, and unprofessional to me. Much like the sweater-tossing antics I observed based on the meebo room conversation in the social media metrics talk, I internally rolled my eyes and thought, how many people are just trying to get attention, drawing it away from the panelists disrespectfully? Is this online behavior and real-life behavior only as mature as the junior high lunch room?

On the other hand, if all the panelists preach about user-centered content, then when the choir stages an uprising, the preacher should be able to adjust his message to fit the audience. Right? I really admired Tom’s quick thinking. I was admiring the way that Tom handled the panel, ensuring that the podcast recording turns out well also, by having each speaker introduce themselves so that listeners later can identify voices while listening.

But enough about the conflicts and struggles going on between panelists, interviewers, and SXSWi attendees. This year, my interaction with other attendees has been the most exciting and fun for me.

Before and after the social media metrics talk, I befriended two guys from Washington, DC, and Summer from Austin who were all sitting around me.

I ended up giving a ride up Sixth Street to David, one of the guys from DC, and he and I had the nicest conversation on the way to BarCamp. I had asked about the conversations that occur on wikis and how interesting it was that the WoWiki panelist George Pribel said they never want to answer how to or troubleshooting questions on their wiki, that they only wanted articles and discussion around strategy. I said that as a tech writer, I was looking for the best use of wikis for content, but since we usually live nearest to and offer the most value to the customer support department, our wikis would be shaped more towards howto and troubleshooting information. However, best practices and strategy wikis might be more easily shaped for conversational articles, so, which was the better approach? His answer was spot on and an excellent example that will stick with me. He said, it’s just like the real world conversations you have in a crowd. If you and I are talking about movies, and someone comes up and starts talking about their favorite restaurant, we would politely inform them that we’re talking about movies, and could you take your food conversation elsewhere, maybe to the person sitting next to me? It’s a matter of staying on topic. With wiki design, I would conclude, you might want to prepare for two audiences (and two types of conversations), just like Lisa Dyer has done at Lombardi Software.

After attending David’s talk, WhiteHouse 2.0 at Barcamp, I learned that he’s former White House Internet and Communications Director David Almacy! He started RSS feeds and podcasts on iTunes and Tivo for the president’s white house. He wrote a Barney Cam script that got posted on Youtube and had over 25,000 views that season. As it turns out, he has two daughters nearly exactly the same age as my two sons. Our youngest kids were born within three days of each other. He was so nice and professional, a knowledgeable expert who is also willing to share his experiences. Prior to the social media metrics talk, I babbled about how I was a blogger for Ynema and Tom on talk.bmc. Little did I know of my fellow attendees level of experience with social media, but I was so pleased that David didn’t try to prove just how much more knowledgeable (and famous) he is than I. Instead he just answered my questions and truly listened to me.

I’m still amazed at the serendipitous meetings and conversations. Yes, the attendees make the conference interesting, and the panelists are bravely facing those attendees.

Stewart Mader has created a series of videos available at www.ikiw.org/21days called 21 Days of Wiki Adoption.

Each video is short, encapsulated, and easily digested when you need a break. I’m really enjoying them, and the cool US map background behind Stewart.

Day 12 is Documentation. Great ideas there, involving authoring in the wiki and using the wiki engine to publish a PDF. I’m working on a blog entry describing authoring in DITA and outputting to a wiki, but it’s also nice to hear of the other way around.

I’m thoroughly enjoying the new Rockley Blog at http://rockley.com/blog/. I’m so glad Steve Manning and Ann Rockley are blogging, especially about wikis.

I appreciated Steve’s post “Wikis for Documentation” especially where he says that the delivery side is the weak point still. Agreed, but I have seen pockets of improvement there and need to be blogging heartily about them.

About three years ago I was equally as unconvinced of a wikis usefulness for end-user doc. An Agile-advocating developer mentioned the idea of using wikis so that the end-user doc could stay in sync with their fast Agile iterations. Yipes I thought! Wikis did work well for convincing the developers to contribute their knowledge, though, and internally they became a useful knowledge sharing (and finding) system.

Now I’m starting to see more and more actual customer need for them. I just had a great discussion about the difference between what a customer needs and what a customer thinks he or she wants, though, so some of what’s necessary is interpreting whether a wiki can fulfill a customer need. I got a small chuckle out of the title of this blog entry - Wikify Documentum Already - but he’s talking precisely about the gains you and your customers make when documentation is in a wiki. The interesting momentum going now is whether the current large enterprise content management systems can start to see the value in a wiki output, or whether the wiki engine providers themselves are going to catch up with the full feature set available in the large enterprise systems.

But wow, I’m learning how difficult wiki maintenance and trust patterns can be while using the wiki.laptop.org site to help out with their end-user doc. In some ways, wiki doc is more difficult than using the real CMS tools that we’ve become accustomed to (read: spoiled by). But I’m also learning how amazing the collaboration opportunities are when using a wiki. I’m still marveling at the communication going on in the discussion pages as well as the volunteer spirit that has come through a request on an art network.

So, what to do to get decent output for content delivery using the multiple channels that us advanced single-sourcers are already accustomed to? I’m planning to move the XO’s end-user doc towards the Flossmanuals.net model of a highly customized Twiki implementation where you can get and print a PDF from the wiki. I can’t wait to learn more and I’ll blog about it as I find out. It’s a step in that direction, though, where you deliver user guides and online help and web sites tailored to the needs of specific audiences. Language translations in a highly distributed environment are going to be an important part of the project, and I’m curious about how Flossmanuals provides for that aspect.

I’ve learned that you can write a Confluence plug-in that will take DITA source and turn it into wiki text. Confluence has PDF output capability as well, so it’s another step in the right direction to get that just-in-time content delivery that a customer needs (but doesn’t know that they want.)

Putting documentation in a wiki (or any really-well-indexed web location, really) can increase findability. If you get internal comments that say “you haven’t documented this particular feature enough” and you feel the feature is sufficiently documented, examine the findability of your documentation.

Also in our user advocacy role we are learning how to listen to customers and then interpret their needs. As information acquisition continues to gather speed, we not only provide the information but should also make informed choices about delivery methods.

Examples of what a customer wants but might not know that a wiki can deliver:

• What’s new with the product?
• How do I interact with documentation, support, the company represented as an actual live person?
• I want immediate information updates.
• I want to discuss the nuances of an implementation decision.
• I need to find others who are attempting what I am in the same type of field (insurance or banking).

What are your thoughts? Are we spoiled by our advanced delivery systems and waiting for wiki engines to catch up? Or are wiki authoring and delivery systems already giving us collaborative opportunities that are unparalleled?

Does working in an Agile development environment change the documentation plan, or user information plan?

For many writers, the purpose of a doc plan is to inform the stakeholders what you (or your team) intends to deliver for docs for a particular product release and when you will meet key milestones.

Here’s an outline of a typical user information plan that includes signoffs from interested parties, with the goal being that you work with your team to agree to what information deliverables are necessary for a software release to be complete.

1. List of deliverables
2. Risks and dependencies
3. New features
4. Documentation milestones and deadlines
5. Techpubs expectations and assumptions for meeting the deadlines

That outline was from an actual doc plan from about three years ago. It was feature-dependent and waterfall-driven.

In an Agile environment, the doc plan might be more minimalist, listing only:

1. key players
2. release theme and top features in the release
3. dates

Then the real work of planning the details of what needs to be addressed in the doc happens during iteration planning. The detailed planning may not be written down in a doc plan, spending the time on writing the end-user doc instead.

I suppose the most Agile doc plan would be a simple verbal agreement to what will be in the doc each iteration.

If there’s a sliding scale, what is the least Agile doc plan? What is the most Agile doc plan?

Our tech pubs group enjoyed Scott W. Ambler’s “Calculating Documentation Cruft” article in Dr. Dobb’s Journal related to Agile methods and documentation. We had some fun in an email thread and I’d like to capture some of our discussion here.

Scott cleverly turns CRUFT (a geek term that either combines crust with fluff or refers to a lab where useless objects piled up in the hallways) into a measuring stick for the effectiveness of documentation:

• Correct = The percentage of the document that is currently “correct”.
• Read = The chance that the document will be read by the intended audience.
• Understood = The percentage of the document that is actually understood by the intended audience.
• Followed = The chance that the material contained in document will be followed.
• Trusted = The chance that the document will be trusted.

Typically, I focus on Agile and end-user documentation, but Scott dwells on the type of documentation that you use while developing the software. Knowing that the Agile manifesto doesn’t value comprehensive documentation over working software, the fact that he’s calculating cruft in a document is refreshing and unexpected. However, my co-worker Shannon Greywalker and I both thought his algorithm could use some refinement. Shannon, being a math whiz, was able to re-mix it and gave me permission to post the idea here.

Shannon says “His formula is essentially 1 – (C * R * U * F * T) = a flat percentage “cruft” rating, wherein higher values are worse.

Let’s assume a perfect score for all 5 values (100% or 1.0 for each). It’s 100% correct; will have a 100% chance of being read; and will be 100% used, followed, and trusted.

1 – ( 1 * 1 * 1 * 1 * 1) = 0.0 = 0% CRUFT. An ultimate low score and so far so good.

Now let’s assume a 99% score for all 5 values:

1 – (.99 * .99 * .99 * .99 * .99) = 0.049 = 4.9% CRUFT. Our score has jumped almost +5% from 0. Still looks okay, mostly…

But now let’s assume scores of 40%, and 30%, for all 5 values:

1 – (.4 * .4 * .4 * .4 * .4) = 0.989 = 98.9% CRUFT.

1 – ( .3 * .3 * .3 * .3 * .3) = 0.997 = 99.7% CRUFT.

The curve produced by his formula is sharply logarithmic instead of linear. Logarithmic curves are the hardest for most of us to use in everyday life just because most of us can’t natively compare one logarithmic value to another.

The best example of an original formula that is not human-intuitive and therefore not all that useful is the Richter scale for earthquakes. The average layperson has no idea what those numbers really mean because 6.0 doesn’t sound that much worse than 5.0 - but it is much worse, because the Richter’s a logarithmic scale.

A more straightforward, intuitive, and linear results curve would be expressed by the formula:

1 - ((C + R + U + F + T ) / 5)

Examples:

With a 60% score in all 5 factors: 1 – ((.6 + .6 + .6 + .6 + .6) / 5) = 0.4 = 40% CRUFT
With an 80% score in all 5 factors: 1 – ((.8 + .8 + .8 + .8 + . / 5) = 0.2 = 20% CRUFT
With the scores from Scott’s example: 1 – ((.65 + .9 + .8 + 1.0 + .9) / 5) = 0.15 = 15% CRUFT “

I would take it one step further, with these descriptive ratings:

40% CRUFT, “document is getting a little crufty” rating

20% CRUFT, “the cruft hasn’t yet overtaken your doc” rating

15% CRUFT, “this document is approaching cruft-free” rating

Shannon’s argument is a good one, the best way to increase the understandability of the CRUFT rating for documentation would be to create a linear calculation for it.

Shannon also argues that there should be a weighting factor for each of the five factors used in scoring a cruft rating. Now, I say that people would disagree on which factors are the most valuable in a document, so weighting might overly complicate the calculation.

I also find the weighting to be too subjective because it seems that Correct could influence Trusted (docs that are found to be incorrect are then distrusted). Also, Understood is elusive for a writer to measure and also to target that specifically - if a selected audience member doesn’t understand what you’ve written, is that always the fault of the writer?

I do like Scott’s tips for creating less crufty documentation, most of which can also be translated for end-user doc. Here’s my attempt at translation for end-user docs.

Scott says “Write stable, not speculative, concepts.” Scott’s talking about writing conceptual information only when its factual and can be trusted. For end-user doc, sometimes writing the concepts out helps you uncover problems, so I would argue that it’s better to write some concepts even early on.

Scott says “Prefer executable work products over static ones.” Scott’s talking about using test executables for code rather than documenting the code and its limitations. For end-user doc, I think that an executable work product could be a screencast or live demo sandbox that lets people try out a feature safely, or perhaps having a link in the online help that opens the dialog box in context like Windows Help in Windows 98 that would open the Control Panel being described in a task about setting display resolution.

Scott says “Document only what people need.” Amen, brother, preaching to the minimalism choir. Know your audience before you write down words that will be cruft.

Scott says “Take an iterative approach.” All writers know that re-writing is as essential as writing.

Scott says Be concise.” Agreed.

What are your thoughts about calculating documentation cruft? Are we taking it way too seriously, or is there a good tool in this (possibly crufty) post?

This article was original published in the June 2007 issue of the CIDM Best Practices Newsletter. It is re-published in its entirety with the permission of the Center for Information Development Management.

In this article, we examine an increasingly popular development methodology from the Extreme Programming family—Agile development—and how technical writers can operate successfully in this methodology. We answer the first questions technical writers might ask when assigned to an Agile team:

• What is Agile development?
• How does Agile development affect my role on the team?
• What are the best methods for succeeding as a team member with this software-development methodology?

The experiences we discuss come from using Agile and a related methodology, Scrum, in creating enterprise software, like database administration tools, rather than Internet applications like Yahoo! Photos. This distinction is necessary because of the vast differences in the length of release cycles; enterprise software teams deliver in three to nine month cycles, while some Internet software teams deliver in cycles as short as two weeks. These differences mean that the implementation of Agile development varies greatly. Now, let’s look at some guiding principles of Agile development.

Agile Development Defined

The main principle of Agile development is to develop robust software rapidly with minimal expense and investment in detailed, up-front design. “Robust” and “rapid” are manifested in the use of iterations, or short development cycles (usually 2–3 weeks), in which a particular piece of the software is developed, tested, and documented. A development cycle built on iterations allows for rapid and continuous delivery, and it provides agility and flexibility that are missing in more traditional development methodologies. Problems are quickly discovered, and teams can either immediately correct a problem or eliminate an affected feature altogether without wasting design work that would have occurred in traditional methodologies, such as waterfall.

The Agile methodology is part of a large family of development processes and has no single, prescribed method. Many companies create their own Agile methods while using some of the original ideas and principles defined in the Agile Manifesto (http://www.agilemanifesto.org/).

A basic tenet of Agile methodologies is “Working software over comprehensive documentation,” meaning that internal design and specification documents are minimal or non-existent. Many technical writers struggle to be fully functional in such a development environment. Writers have traditionally relied on design documents to get a “big picture” of the product—what it does and how it works. The amount of internal documentation varies widely among Agile teams. Some teams do not even produce a list of product features, relying instead on their Agile planning software to act as a repository of the list of stories and tasks to be accomplished in each iteration.

Another tenet of Agile, “Individuals and interactions over processes and tools,” can make writers feel marginalized when determining how best to function in the team. Fortunately, the best Agile teams understand the value of end-user documentation or can be shown that an integral part of creating successful, working software is excellent documentation written in a tightly collaborative environment. In such an environment, the technical writer can adapt and even shine.

The Language of Agile Development

Often the most intimidating part of learning anything new is grappling with a new vocabulary, and Agile is no exception. Following are some basic terms that are used frequently in Agile teams:

• Iteration: A period of time during which the software is programmed and at the end of which the quality assurance (QA) testers verify that the software is working as expected.
• Stand-up: A daily meeting in which the progress of the software development is communicated.
• Story: The business need that defines what the software will do for the user. Stories are usually sized so that a single iteration is enough time for development, and they are usually written as “role can do task” (for example, “An Administrator can add a new User”).
• Task: Defines all of the subtasks for a single story. For example, for the story “An Administrator can add a new User,” one of the tasks might be “Connect the new component to an existing security component.”
• Backlog: A repository for stories that are targeted for release during an iteration.

How Does Agile Affect Your Role and Processes?

As part of an Agile team, you are expected to tell the team what you will deliver at the end of an iteration. Working in iterations has a definite affect on the scope, content, and presentation of your deliverables. You must be prepared to communicate your status daily because many Agile teams track progress on all stories and tasks daily.

Some techniques and certain deliverables are well suited for documenting products that are developed in an Agile environment:

• using a topic-oriented approach such as the Darwin Information Typing Architecture (DITA) or Information Mapping^TM
• leveraging user stories to produce task-oriented documentation
• applying minimalist principles
• participating as an active team member

Topic-oriented writing

Most writers are familiar with topic-oriented writing: authoring concise, self-contained units of information about a specific topic. Topic-oriented writing is a defining aspect of Information Mapping and DITA. In Information Mapping, complex information is broken down into basic components, and then the “chunks” of information are structured in a reader-friendly way. In DITA, information is categorized into concept, task, and reference topics. Such categorization makes sense in an Agile environment, in which “the right documentation at the right time” is the main goal for all documentation, end-user and internal.

In addition, DITA maps offer just-in-time assembly and output generation of documentation, which provides a huge advantage when creating Agile documentation. In an Agile environment, changes that make the software better, even at the end of an iteration, are welcomed and encouraged. But if a new function is eliminated from an iteration after you have already documented it, you just remove those topics from the DITA map for that iteration’s build. Keep those topics for the next time that feature is worked into a user story, and you become the hero when you link those topics in a new DITA map and generate output.

Translating User Stories into Task-Oriented Topics

In an Agile environment, development is driven by user stories, which define the tasks that end-users want to accomplish with the software. User stories must be customer-focused, succinct, and testable, and writers can leverage them to create user-focused, task-oriented documentation.

Task-oriented writing not only complements development’s use of user stories, but it is an absolute necessity given short iteration cycles and an often limited number of writing resources. The requirement to create installation and configuration information and solid procedural information (probably in an online Help system) often leaves little time in any release cycle to create much conceptual or best practices information. Such information can, however, be produced following a particular release cycle. The focus on tasks within a cycle, however, helps writers achieve minimalism, another technique particularly well-suited to documenting in an Agile environment.

Just-In-Time Documentation Also Means Just Enough

Minimalism in technical documentation has been advocated since IBM’s John Carroll wrote The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill in 1990. Minimalist principles are especially relevant when you adapt Agile methods to produce working documentation that complements working software at the end of short iterations. For example, you should avoid wordy overviews that are not task-based, and you should not even document obvious procedures such as how to cut and paste text or print reports.

The Importance of Team Spirit

Being an active member of the Agile team is crucial to a writer’s success. The lack of internal documentation makes full participation in the team an absolute necessity. Your awareness of hallway conversations and impromptu white board drawings about changes to the GUI, for example, could mean the difference between completing your stories or tasks within the specified iteration or not. The need for such camaraderie obviously must be understood and embraced by the developers and testers on your team.

Ideas for Best Practices

Having survived and thrived during releases using Agile methods, we have a few ideas for best practices, as well as pitfalls to avoid:

• You will be most successful if you are dedicated to a single Agile team, not a resource shared by several Agile teams. This focus enables you to attend all meetings, like the daily stand-up, where you can gather information and overcome roadblocks.
• Encourage and embrace the face-to-face communication that is a driving force in Agile.
• Locate your workspace near your developer and QA teammates if possible. If you cannot work physically near your Agile team, find ways to communicate as personally as possible in real-time, such as using Instant Messaging or web cameras with video conferencing.
• Agree with your development team on two key points:1. should the documentation tasks be included in the development team’s story or housed under a separate, documentation-specific story?
  2. how many iterations can the end-user documentation lag behind the development team’s completion of a feature?
• Write user stories for documentation that parallel the user stories that are being used to build product features. An example user story for documentation might be “A DBA can read online Help to learn how to manage licenses.” An alternative is to create documentation-specific tasks that are included under the development team’s user stories. For example, the development team might have already created a story called “A DBA can manage licenses”; as the writer, you can simply add a documentation task to the story. Another idea is to house all documentation stories and tasks under a parallel project, so that you can easily estimate documentation’s velocity.
• You must have access to the same planning tool that the Agile development team is using. This tool may be software based, such as Rally or XPlanner, or it may be index cards on a cork board. The ability to create entries gives the documentation tasks equal visibility and footing with development and QA tasks related to each user story. In some environments, the planning tool is the only place to see a comprehensive list of the product’s planned functionality, as represented by the stories.
• Request that all user stories be stored and accurately maintained in a single place, which will most likely be the Agile planning software. Ideally, the product manager or development team creates a product feature list or some document that states all of the product functionality.
• Write a minimal documentation plan so that you can focus on story planning and end-user deliverables. The documentation plan could list the key contacts, release theme, top stories, dates, and your expectations and assumptions.
• For each user story, ask the QA team to create an equivalent task for reviewing the online Help or other documentation.
• Request a “hardening” iteration in which you can complete final tasks for your deliverables—for example, check index entries on final assemblies or determine the optimal organization for a table of contents. Final user stories for documentation might end up in a “hardening iteration” that includes technical reviews.
• Use the backlog to house documentation tasks. First, pull high-priority, low risk items from the backlog into an iteration, and then return to the backlog for lower-priority or higher-risk items in another iteration.
• Keep your documentation task-oriented, in line with the user stories that are promised with each iteration. If you want to take task orientation to the next logical level, write your end-user documentation in a topic-oriented way with tasks having supporting concepts and reference topics, much like the DITA prescription.

Conclusion

Just as programmers employ Agile techniques to improve their deliverables, technical writers can employ complementary writing techniques to become an integral part of delivering useful software. End-user deliverables that are task-oriented and help the user perform at an expert level become a necessary and valued part of the success of a product developed using Agile methods.

Bibliography

Beck, et al., Manifesto for Agile Software Development http://www.agilemanifesto.org

Broderick, Stacia and Melody Locke. “A Tale of Two Writing Teams.” agile, pp. 295-304, AGILE 2006 (AGILE’06), 2006.

Cohn, Mike. Agile Estimating and Planning Prentice Hall PTR, 2005

About the Authors

Tana Berry
Senior Technical Writer
Database-Brothers, Inc.
tana.berry@database-brothers.com
Tana works as the only technical writer at Database-Brothers, a small company with a focus on database auditing and performance products. She has enjoyed working as a technical writer for more than twelve years and has been an active team member on an Agile team for a year. Tana loves Agile because it forces the writer to produce lean, task-oriented documentation with the end-user always kept as the focus.

Anne Gentle
Senior Technical Writer
BMC Software
anne_gentle@bmc.com
http://talk.bmc.com/blogs/anne-gentle
Anne Gentle works at BMC Software where she writes technical deliverables ranging from user manuals to online help to white papers. BMC has many product lines adopting Agile development methods and the product Anne now writes for, Configuration Management, has recently become Agile. Known to enthusiastically discuss communication topics ranging from blogging to wikis to XML-based information models like DITA, she sees DITA as an excellent gateway to more Agile documentation.

Inner gang? Mini empires? Am I talking about the online encyclopedia, Wikipedia? Why yes, yes I am. I’m reading “Who Writes Wikipedia” which is a study on how Wikipedia is edited and maintained. Is it really “a small group of colleagues working together toward a common goal?” A small group wrote that much content in about four years?

I’m interested in this subject because Wikipedia is a wonderful reference site full of content that usually is accurate and rings of authority even though it is maintained with an all-volunteer content creation and editing team. Seeing it and liking the results, I wonder how a wiki could be used in a similar fashion to build technical documentation sites that are user-built and maintained while offering the best, most thorough, most accurate technical information about a certain product or technical subject. Could we really get as valuable a reference for product doc by having a “small group of colleagues working together towards a common goal” — a goal of an excellent set of product documentation online?

Outsiders provide content, insiders clean it up

Come to find out, according to the article, over half of the edits are done by less than 1% of the users, about 500 people are considered to be the inner circle of editors, building consistency in wording and categories while fixing typos and editing content where needed to build more quality into each entry. The most active group of about 1400 people have done nearly three-quarters of all the edits. These statistics and claims are made by Jimbo Wales, the face of Wikipedia. Now, the article’s author, Aaron Swartz, tracks a few more nuances of this claim by studying random wikipedia entries, such as the one for Alan Alda. And here is his conclusion based on his study:

When you put it all together, the story become clear: an outsider makes one edit to add a chunk of information, then insiders make several edits tweaking and reformatting it. In addition, insiders rack up thousands of edits doing things like changing the name of a category across the entire site — the kind of thing only insiders deeply care about. As a result, insiders account for the vast majority of the edits. But it’s the outsiders who provide nearly all of the content.

Wiki for tech doc

Now, I’d like to try to translate this to what might work well for a wiki geared toward product documentation. You’d need a core set of very knowledgeable content providers, like a team of experienced users of the product. Those users would contribute a core body of knowledge to the wiki, and hopefully choose to first document the items that are either most popular tasks or the most-referenced information or the toughest concepts to grasp. Most likely that would be the subject matter they’d be most familiar with anyway.

But is there vandalism?

It also appears that my wiki graffiti concerns are likely unfounded… the article says, “A tiny handful — probably around 5 out of nearly 400 — were “vandalism”: confused or malicious people adding things that simply didn’t fit, followed by someone undoing their change. That’s such a small percentage, just over a tenth of a percent, that it seems for the most part there are few writers with malicious intent in their edits.

Real wiki writers tell their experiences

Reading through the comments, I also appreciated the “user experiences” from people who are actively editing Wikipedia content. One commenter notes that he “went crazy” adding content in areas where he had knowledge but found that once his knowledge limitations were surpassed or the well was dry, he went into a maintenance mode. With a “burst of new knowledge” he’d add more content to those areas but found those to be few and far between. I think that with product documentation a similar ebb and flow would occur — knowledge or experience with a relatively new feature would cause activity on certain articles but then maintenance would occur again.

How do you get enough contributors?

Probably the major limiter for a product documentation wiki that’s maintained by users is that the user base would have to be significantly large in order to draw enough content providers. If 500 people maintain Wikipedia, you’d probably need 50,000 users to get 500 committed people to provide content (or would you actually need half a million?).

How do you ensure consistency?

Wikipedia has a basic information model to follow that most people are familiar with, also — the encyclopedia and it’s article-like writing style and the content you expect to see in an encyclopedia is well known and the style is easily copied by any writer. Product reference would need some excellent modeling to follow, which is why I lurve the idea of a DITA wiki — structured content models that 500 people could follow consistently, writing concept topics, tasks, or reference topics on a regular basis.

I’m warming up to the wiki

We can learn a lot from Wikipedia’s success and I plan to continue to track their progress as it evolves and more policy is put in place. Perhaps the wiki has potential as a great product doc format.

What do you think as a writer? Would you be willing to write and maintain content for product doc in a wiki? What do you think as a product user? Would you want to read and would you trust the content provided by thousands of fellow product users? Maybe I should experiment by combining the two groups — user and writer — and start a FrameMaker wiki. Surely the FrameMaker user base just isn’t large enough to generate the content it would need to succeed. What do you think?

Yes, the quality of the documentation will be noticed when it stands above the crowd, and people will compare technical docs product to product. This article titled Solaris Review: Solaris Welcome Home! by Brandon Werner that I found on James Governor’s del.icio.us list has a great section talking about mature documentation (and even hints at the inadequacy of wiki for technical documentation, although I won’t interpret beyond what he might have intended). Here’s an excerpt from the relevant section. A good read.

Solaris 10: Documentation without the O’Reilly Tax.

What really separates Solaris 10 from the pack is the documentation. If you don’t think you’ll take advantage of documentation, it’s only because you grew up without it on Linux, and Google has been your only recourse. Solaris did not grow up in the world of HTML HOW-TOs and Wikis. Far from it, there is enough documentation online to kill a rainforest if printed. And it’s really good documentation too; documents that walk you through everything you’d ever want to do from setting up Sendmail to using NIS+ to configuring network services. It has high-level overviews with detailed walk-throughs and advances at the level of the reader by providing quick methods to get started and then drilling down in to the details as people get more comfortable with the services they are deploying.

An interesting side note — Brandon’s in the Cinci area, where I went to grad school and completed my first tech writing jobs. Eat some Skyline Chili for me if you’re in the area, please.