I'd Rather Be Writing » documentation

A Reverse Approach to Help Authoring: Writing Documentation Post-Release

Tom Johnson — Thu, 02 Feb 2012 06:33:20 +0000

When I first started as a technical writer, a senior writer taught me how to write documentation. Her approach, which aligns with the traditional way of doing technical writing, generally followed these steps:

Get involved as early as you can in the software development process. As soon as prototypes are available, or a functioning development environment, start the documentation process.
Think of all the main tasks users will do with the application. Make a list of the tasks and begin documenting them in careful detail.
As the application nears release, finalize your help material so that it’s ready when the application launches.
Once the application launches, move on to another project.

This traditional method of writing documentation places all the work before release. Sometimes I think the bulk of documentation should be written after release. This “reverse method” aligns more with support center philosophy. Some support centers believe you shouldn’t write anything until a user asks a question. Only then do you begin to document answers.

With a reverse approach to documentation, you place more emphasis on the help material after the release rather than before.

But you might object and say that our job is to anticipate the user’s questions and pain points so that when they do search the help file, the answers are there waiting. This in fact is Ginny Reddish’s premise in Letting Go of the Words. She encourages us to imagine a conversation with the user, anticipating their questions and responding as if in conversation.

I think imagination, even user interviews, are good techniques. However, too often I skip over this. I end up giving nearly every topic equal attention, documenting with careful detail both the obvious tasks and the difficult tasks. My imagination is usually an extension of the product manager’s vision and understanding, which I inherit from dozens of project meetings. The closer and more involved I get into a project, the less clearly do I see all the assumptions I’m making, the workflows I’m immune to, how blind I’ve become. No one can predict the future. How often have our anticipations and imaginations perfectly matched user reality? Do we even know the user’s reality?

With the traditional method of documentation, after the application is released, I’m not as closely involved with the project anymore. I don’t have my nose in JIRA; I’m not carefully monitoring all the incoming feedback. In my mind, I’m done. User pain points and frustrations often go unnoticed, while my attention shifts to new projects. I may add a topic here and there, or add some more detail, but by and large, documentation is mostly done when the application is released. I think that’s a harmful mentality that might be cured by a more reverse approach.

Let’s rethink the model. With a post-release documentation emphasis, the technical writer pays careful attention to every incoming question, comment, and feedback item from users. Whether through support center calls, forum questions, feedback emails, webinars, or other channels, the technical writer carefully monitors each question and begins building the help material from these questions. User feedback drives and shapes and structures the help material. It determines what we write, how much emphasis topics receive, and how visible we make those topics.

Now I’m not an extremist. I know that some help material is necessary when an application is launched. Quick reference guides and some basic help material would probably suffice. It would give something to the user to get started and not feel alone or abandoned. In some cases, a short series of video tutorials might also be helpful. After all, users need the most help when the application is newest to them, that is, when it’s first released. Abandoning the user in their time of greatest need may seem somewhat cruel and unproductive. I’m not saying no documentation should be written prior to release.

And yet, the long help file can wait. Wouldn’t we be much better to start writing help in an intensive, 100% heads-down manner during alpha and beta testing periods, and then during the first month of release? After all, how much time do we waste trying to figure out how a partially-built, bug-ridden application works in an unstable development environment? Wouldn’t our time be better spent waiting for the application to reach a near-production level, and then once that level is reached, focus all our energy on creating help material for it, based on questions and issues and frustrations users are experiencing?

Without a launch date for an application, there’s no clear date when documentation is done. In this post-release, reverse model, documentation can keep growing as long as users continue to ask questions and experience frustrations. Documentation is probably finished when the incoming feedback dies down, when most of the incoming questions can be answered with simple links to answers in the help.

Feb 3 update:

Check out this video from Greg DeVore that expands on some of the points I make in this post:

For a contrasting perspective on the idea of reverse documentation, see this post by Kristi Leach, When is it time to hire the technical writer?

Blog Sponsors

Brainstorming Solutions to Volunteer Management/Engagement

Tom Johnson — Wed, 01 Feb 2012 15:56:27 +0000

I am constantly reflecting on the answer to this question: How can I draw upon the enthusiasm, intelligence, and skill of willing volunteers all around me to take our organization’s site to the next level? This goal mostly relates to my involvement in my organization’s technology blog, which has about 80 volunteer writers.

In my post about what I learned during 2011 as a technical communicator, I wrote:

Community collaboration is extremely tough to pull off. I can’t just assign a volunteer writer a topic and let them run with it. I usually have to either gather the information from a subject matter expert or connect the volunteer with a subject matter expert — and then see them through the process with more hand-holding than I want to provide. Still, community volunteers can generate momentum by the sheer number of assignments I have to follow through with. Overall, I have no idea how to engage community volunteers in an effective way, but I think I can eventually figure a strategy out. (See What I Learned About Tech Comm During 2011.)

In response to this post, Saul Carliner added the following insightful comment:

But the challenges of working with “volunteers,” is one that is rarely mentioned when discussing SME-authored and user-generated documentation. Having had worked with volunteers in a number of sectors over the years–from work-related ones to community ones–the issue of volunteer management is one that still challenges all of them. Incentives and clarity help, but not always in the way intended. Even in areas that have years of experience with volunteers, it’s more of an art than a science. Just because we’ve moved to community-based approaches to documentation and the wikipedia has been successful doesn’t mean that other ventures don’t involve nurturing.

The last sentence particularly stands out. Yes, many social ventures (such as Wikipedia and Digg) have been hugely successful. But that doesn’t mean applying the volunteer model to tech comm is a process or technique we understand. It’s an art, and one that most community managers still struggle to figure out.

The topic isn’t just limited to volunteer engagement. SME-authored documentation, as Saul mentions, also fits into this genre.

In a series of questions I responded to on Ugur Akinci’s blog, I reflected at length on what is the most significant change in the field of technical communication. It fits right in with collaborative efforts and social intelligence. Here’s an excerpt of my response:

QUESTION (3): What is the single most important change that you see in the technical communication sector since you first became a technical communicator?

… The greatest transformation yet to come is to drop the single-author paradigm of technical writing and to embrace the way information flows on the web. … For years help authoring has consisted of one person (or just a few people) writing help material. When content comes from one person, the content is usually limited in perspective, accuracy, and applicability. Writing needs to become much more collaborative, and not just from inside the corporation, but outside as well. Documentation is never finished. When I log off for the day, someone out there may be contributing to the documentation, making it evolve, adding sections, correcting errors, expanding on special cases, and so on.

It’s engaging to come into the office in the morning and review the latest changes to the wiki, to find that someone added a new section, or a new page. We no longer have documentation as static, standalone files that are written in haste by one technical writer and then “finished” as he or she moves to the next project. Documentation is a living, breathing body of information – like the web. The web is in constant flux. It’s full of a whole landscape of people – trolls, spammers, forum champions, lurkers, relentless volunteers, bloggers, programming whizzes. All of these people, like characters in a circus, come together on the same stage, interacting with each other in rich, multifaceted ways. Sometimes these interactions are exciting, other times they’re frustrating. But either way, documentation evolves to become more web-like in the ebb and flow of information.

This ebb and flow of information is what I find most rewarding about technical communication. Information no longer emanates from one source but rather connects into a greater body of people. This is the genius of the web. The web thrives because of this content interaction — one person building on the ideas of another in collaborative, interactive ways. (Read the full interview on Ugur Akinci’s blog.)

Let’s come back to the original question. How can you harness the enthusiasm and talent of volunteers in productive ways? The answer to this question wouldn’t just be a neat technique to enhance productivity; it would change everything about my job.

The problem is not content strategy; it’s content tactics. The strategy is clear: draw upon the talent and enthusiasm of willing volunteers to write high-quality content. The details of how remain a mystery. Let me continue my brainstorm.

Challenges

Several main challenges make this a difficult problem:

Volunteer writers often don’t have the information necessary to write articles.
SMEs with the knowledge often don’t have the interest to write articles.
Content that volunteers write, even if informed, often needs significant editorial processing before it’s ready for publication.
Writing assignments often need more detail before you can assign them to volunteers. If you can only gather this information internally, it makes it difficult to assign to volunteers.
The remote distance between headquarters and volunteers makes collaboration and communication more difficult.

Known Principles that Work

Now that I’ve outlined the challenges, let me also outline what I’ve learned about volunteer engagement:

People are much more likely to accept invitations when invited on a personal level.
People are much more likely to accept invitations when they have a relationship of trust with you.
People need a clear understanding of what you want them to do.
People need deadlines to understand when you expect them to finish their assignments.
People need regular communication so that you can address issues and other concerns that might be obstacles.
Communicating on a personal level, building trust, establishing deadlines, providing detail, etc., takes significant management time.
People need opportunities to pursue their strengths. Not everyone is a creative writer. Many people function better as editors.
People need access to information, people, and meetings to write the content that is expected of them.
Content often goes through successive levels of edits before it’s ready for publication.
People have a limited amount of time to work on articles they are not getting paid for.
People like to feel that their contributions are valued, not wasted.
Coordinating, tracking, commenting, and following up on assignments for scores of volunteers requires an advanced system to manage all of this information.
People often want to get something in return for their volunteering, such as more experience, understanding, improvement, portfolio samples, and more.
People often overestimate their writing abilities.

Formulating a plan

I recognize that my brainstorming and analysis is specific to my own volunteer situation, and one situation may vary dramatically to the next. Hopefully the tactical plan I form may be of interest to others who work in other volunteer situations, even if the details vary. Given the challenges and known principles, what would work well for success?

Here’s are a few potential first steps:

Step 1. Create a body of work that volunteers can do. This means crafting assignments that are important and worthwhile. Creating a body of work may be the most difficult of all steps, as this requires me to add detail and potentially outlines to topics. Sometimes I may only have an idea for a story, or a name to contact, not an actual story in hand. But having a tenuous idea doesn’t work well for volunteers, who may be playing guessing games at what I want. The details of the assignments need to be clearly spelled out. Each writing assignment needs to have a basic level of clarity to be something that users can actually accomplish. Contact points, key messages for the article, length, tone, and other details should be clearly defined.

Step 2. Personally invite volunteers to act. The second step would be to personally invite volunteers to work on the tasks they’re assigned. The invitations should ensure that the writing assignment is a good fit for the volunteer (that is, matching the volunteer’s strengths and interests), that the volunteers have a good idea of what you expect, and the due date.

Step 3. Regularly review, track, and follow-up with assignments. It would be a good idea to review all the items stored in the system (in my case, JIRA) on a daily basis so that I don’t let some assignments languish and become forgotten. Volunteers may run into insurmountable issues and challenges; they may realize the assignment isn’t a good fit for their interests. By following up and checking in regularly with volunteers, I also demonstrate the value and importance of the assignment.

Step 4. Have volunteers edit volunteer writing. This is one of the steps that I’ve never implemented, but it might be good to have volunteers edit other volunteers’ writing. Writing often needs successive levels of editorial review. I could provide some quick comments and feedback, and then either have the volunteer make revisions or pass it to another volunteer to make edits, and then potentially to another volunteer. This way by the time the writing falls on my desk, it’s already to a level that is near publication quality. In some situations, I could ask SMEs to write content and then pass it along to volunteer writers to edit.

Step 5. Communicate regularly. Without regular communication, people lose interest. They quickly drop off. The communication also helps build trust, and people may feel as if they’re learning more from discussions. It’s not possible to build a lively community without regular engagement through e-mail and other online interactions. Perhaps contributing an e-mail a day may go a long way toward building trust and helping volunteers feel that they’re getting a lot out of the experience.

Conclusion

No system works if one doesn’t use it. These five steps aren’t rocket science. I could probably have a decent amount of success implementing them. The problem is maintaining regular activity, sticking with the system week after week, especially when other, higher internal projects get in the way. This is perhaps why breaking the tactics down to even a more concrete, daily to-do list might be a good idea.

I’m interested to hear what strategies you use for managing volunteer writers.

Blog Sponsors

The Case of the Stolen Documentation

Tom Johnson — Wed, 06 Jan 2010 07:14:44 +0000

Some months ago I created a half a dozen quick reference guides for an application that would have a potential audience of thousands of users (after it cleared the beta phase). The size of the audience gave me hope that I would actually create documentation to be used by more than a handful of people outside the internal workings of my organization.

I created the guides in Adobe InDesign because it seemed to make sense for the situation — the application was relatively simple, and there were just a few roles. I crafted the layout and design carefully, branding the guides with the same color and feel as the application. I meticulously ensured each task was described with concision and accuracy, and I limited the text for each guide to one double-sided page to avoid intimidating the users. During each application update, I reviewed the guides against the new use cases and updates and made sure the instructions matched the new functionality.

As you know, I’ve given several presentations about quick reference guides and have written about them numerous times on my site, even calling quick reference guides the poetry of technical writing. These six guides were my poems. I felt a sense of pride with them and displayed them in my gallery of quick reference layouts and during team meetings.

And then one day, I received a phone call. One of the clients asked for the source files so she could update them herself (or have other designers update the source files under her department’s supervision).

The source files? I said. They’re in Adobe InDesign.

Yes, please send the originals, she said. I felt a bit offended. No one ever asked me for source files before. I wondered what it was she wanted to update that I couldn’t do. Wasn’t I close to the engineers and project managers, and therefore in a better position to update the documentation? Wasn’t I keeping it all up to date?

But I know I work for an organization, and the products I make don’t belong to me. So I zipped them up and clicked Send. For a long time, that was the last I ever saw of them.

I hung around a couple of project meetings after that, but it was clear that the documentation was now owned by someone else. I was no longer needed. Okay, I said, and moved on to other projects.

For a couple of weeks I felt upset and confused. I didn’t know if I should periodically inspect their updates, if I should close the project entirely, or what. I laid low and continued to work on other projects.

No more emails, no more requests, no more maintenance. It felt as if my documentation was stolen.

Blog Sponsors

Notes Watching Senior Users at the Computer

Tom Johnson — Fri, 06 Mar 2009 13:56:11 +0000

Sometimes the audience for my help consists of seniors in the range of 60 to 85 years old. The other night I attended an orientation session with users to introduce them to a new application we were releasing. As part of the orientation, I observed first-hand the challenges that seniors have with computers. Here are a few user interface problems:

Calendar picker tools are tough to navigate, since the forward and back links are small. In these situations, make the calendar larger and provide a sample date format so users can type it in manually. Also, many users won’t realize they can click the calendar icon to select the date.
Senior users may not be used to scrolling, so if your Next or Continue buttons are at the bottom of the screen, and only visible if you scroll down, the user may be confused as to what to do after finishing a task on the screen.
If the application doesn’t immediately respond when you click a button, make sure an hourglass or some other visual indicator promptly appears, because otherwise users may think the button didn’t work and will click the button two or three times. Also, in your testing of the app, make sure an error doesn’t appear when you double-click a button.
Some senior users tend to focus entirely on the screen, rather than being able to bounce back and forth between documentation and the screen (even when they need to). Try to integrate the help in a context-sensitive way such that it’s combined with the task on the screen (much easier said than done).

Error message Documentation

At the orientation I attended, what users really needed, beyond a more helpful UI, was a table listing all possible error messages in the application and the resolution action for each. Error messages are particularly subtle components that we tend to miss when writing documentation. After all, we’re documenting how the application works, not so much how it doesn’t work.

Also, error messages often don’t appear when you’re doing things right. Only the QA engineer can probably know all the possible error messages, since he or she actively tries to break the system. You can also find error messages by watching users, particularly novice users who often don’t follow standard browsing/navigating/clicking/selecting protocol.

Just because you’re in a development environment, don’t assume error messages are temporary and will be eliminated when the system is released. Instead, take a guilty-until-proven-innocent approach. Err on the side of assuming the dev environment will match production rather than assuming production will be a magical environment where everything works error-free.

Simplification

Today I trained another group of users on an application, and being in a computer classroom, I could observe them at the computer. Again, I was stunned by some things. What I considered fairly straightforward and intuitive, they found tricky and frustrating.

Sometimes when I write help, I mistakenly think of myself as the audience, and will write thinking of tips and how-to information that I personally would need on that page. But this is not the case for many audiences.

Although I’m no tech giant, I do consider myself handy with computers. Most users, at least for my applications, are not comfortable with computers. Computers are a temporary means to an end for a brief period of time, rather than something they work with all day long. Because of this disparity of environments, when I write help, I try to simplify the instructions beyond what I need. I’m not advocating that tech authors write idiot instructions (e.g., click the up arrow to move up), but think of the user perhaps as your grandfather or grandmother.

Part of the problem in writing help is that we explore and play around in applications so long, we lose our first perspective. We lose that sense of disorientation and lost-ness that users have the first time they get in the application and click around. If there were a way to wipe our application experience and start fresh, it would be invaluable.

About the only way to regain this “application innocence” is to observe users. See where they get stuck, what they click, what their first inclinations are to do. Anytime you can watch users in your application, the epiphanies fall like snow from a winter sky — all over the place, and not always pleasant. It can be an awakening to your application and documentation’s usability. This eye-opening experience is one that doesn’t come any other way except through user observation.

Blog Sponsors

Documentation Honesty and Poor User Interfaces — An Ethical Dilemma?

Tom Johnson — Mon, 22 Dec 2008 02:08:06 +0000

Rilynn from New England writes,

Tom,

I notice that a lot of companies use release notes to post a list of defects (bug) that were fixed with the corresponding software release. This is something that I appreciate as a software user. I realize that I’m not the user of my company’s products, though. Also, management at my company is really against adopting this practice, seeing it as “airing our dirty laundry.”

This bleeds over to more general areas as well. For example, I was asked to write a short document to help our users with a task in our software that was, admittedly, not well executed. In certain scenarios, the user had a couple of options that were really more “workarounds,” and neither was terribly elegant. My initial approach was very matter-of-fact and forthright, explaining the pros & cons of each approach. I got some feedback that ultimately lead to me softening the language significantly, to the point that I think the document wasn’t’ as straightforward in helping the user make the decision about which path was right for them.

What do you think? Have you had any similar situations? Do you think most users these days appreciate a more forthright, honest approach, or are they apt to use documentation of our products’ shortcomings against us?

Excellent question. Let me tackle this in two parts.

Apologies and Insults for Poor User Interfaces

We’ve all run in to situations where we have to document poor user interfaces. As much as we complain and suggest improvements, the project manager decides to go ahead with the interface as is because redesigning it is too costly.

When I run into these situations, rather than insult the interface in straightforward talk in the documentation, I euphemize the language (against my better desires) in order to maintain the consistency of the company voice. It just doesn’t sound right to be so frank.

For example, perhaps you have a button in your application that does absolutely nothing, and the developers don’t feel it’s a high enough priority to remove. Rather than say, “The X button does absolutely nothing — it was a low-priority in the design to remove it,” you can write something like:

The X icon in the upper-right corner of the pane does not apply to the pane nor to the tabs in the main window. The X icon is an unnecessary carry-over from the pane’s fly-out functionality and could not easily be removed.

I don’t know if that’s too straightforward, but it maintains the corporate voice without slipping into insults. However, sometimes the issue is more severe.

For example, on an application I document, I realized, about a month after the release, that the home page was missing a critical link to a step in a common process. A confused, upset customer brought it to my attention. My help instructions described a different approach for completing the same process. Should I add a note in the help, warning users that following the steps on the home page, as the application was partly designed to accommodate, would result in confusion and misinformation?

This situation points to an interesting predicament. As technical writers, we play on both teams during the same game. On the one hand, we’re champions for the users, arguing for usability, simplified steps, and a friendly computer experience. On the other hand, we’re also members of the project team, responsible for presenting the voice of the team. When the interface requires an honesty that will put the project team in an uncomfortable light, the only solution is a careful rhetorical explanation that blends euphemism, apology, and alternate options.

Of course, if you’re writing a third-party how-to book, you have an open license to insult the application as much as you want. I routinely see this in For Dummies books and others where the author does not represent the project team company. In fact, one appeal of these books is the author’s open, unrestricted voice.

You can also be abnormally straightforward if you work for a company that has an anti-corporate flair. For example, in a previous version of WordPress, some help text in the UI says the following:

Exactly when can you call your user interface "janky"?

But unless you fit into one of these two situations, you’ll find yourself writing and rewriting those sentences in your documentation, balancing honesty and team voice in difficult ways.

Listing Bugs in Release Notes

You also asked whether teams should list, in release notes, all bugs they fixed. Snagit recently released version 9.1. The first thing I did was look to see if they fixed a little bug that happens when you manually stretch a selection. Sure enough, they did. I was ecstatic. But the fixed bug wasn’t listed anywhere on their release notes (at least the ones I saw).

Perhaps they hoped the majority would never know about the bug. They probably fixed a dozen other bugs I wasn’t aware of. Does “airing their dirty laundry,” as you phrase it, suddenly awaken users to the fact that there are a lot of bugs, instability, and other issues in the application they trust?

Maybe a little. Many users assume that officially published releases of commercial software are bug-free. But that’s not the case for either commercial or in-house applications. In one application we have at work, there are scores of bugs in the production version — but you’d have to ask a QA engineer to find them all. Most are extremely subtle and only occur in rare circumstances.

Although I don’t have any research to stand on, I think it’s a good practice to list all the bugs you’ve fixed (to an extent). The long list of little bugs can be a separately referenced document, almost a footnote in the main release notes. Something like, “In addition to these new features, numerous other bugs and issues have been fixed.” With “bugs and issues,” you can link the text to a long document listing all the fixed bugs. In addition to the benefits of complete disclosure, writing a comprehensive list of fixes will make you aware of changes you may have missed.

Do you run into ethical dilemmas involving honesty and documentation? How do you handle it?

Blog Sponsors

Coding Horror: How to Write Technical Documentation

Tom Johnson — Mon, 20 Oct 2008 14:27:08 +0000

Coding Horror: How to Write Technical Documentation.

How Much Should You Document? Everything? Strategies for an Agile Environment

Tom Johnson — Wed, 10 Sep 2008 03:19:28 +0000

In a recent IT Author podcast (“Documentation and Agile Development“), Alistair Christie and Graham Campbell talk about agile development and its impact on documentation. One consequence of working in an agile environment, they say, is the need to prioritize your documentation, to deliver instructions for only the most important or confusing features.

Presumably, some agile environments move so fast, you have to triage what you document because there’s no time to document everything.

How much should you document? Everything?

Alistair explains that you can’t document everything, and he quotes from Martin Fowler’s “The Almighty Thud.” Fowler, however, takes the argument one step further, arguing that you shouldn’t document everything. Fowler writes,

If you document everything, you are giving everything an equal weight. Do that for a complex system, and you are buried in detail. In any system there are some aspects that are more important than the others, key aspects of the system that once understood, will help someone to learn more. The art in documentation is to find how to document these aspects as clearly as possible. In this you emphasize these areas, and leave the details for the code.

If you document everything, you end up giving everything equal importance and losing focus on the key tasks and concepts users need to learn. You need a focal point, a selection of core tasks that receive prominence and make everything else intuitive.

Fowler continues, citing his own approach to the article he wrote as an example:

As I started to write this article I was overwhelmed by the things I could talk about. Lots of anecdotes and tips came to mind. But I know that to get you to read and remember this article I could only talk about a few of them. I had to select the key things that I had to mention. Communication is all about that. The key to good communication is to highlight the important things to say. Saying everything is not communication. That just passes the selection of the important things onto your readers, and discourages them with a heavy document. That selection of information is one of the most important parts of communication, and it is the responsibility of every designer.

I agree that selection is key to crafting any article. Were his article 20 pages, I wouldn’t have read it so eagerly. Instead, because it’s 2 pages, I did read it.

Alistair says that when you give someone a huge manual (one that makes a thud when you set it down), it makes the user’s heart sink. “They don’t think, Oh, that’s great. No, they think oh, This looks grim.”

Bloating the table of contents with dozens of non-essential topics reduces the focus on what customers need to be concerned about. Each additional word you add dilutes the importance of the other words. “The more you document, the less people read,” Alistair says.

We all know that if you give someone War and Peace, they’ll probably never read it. But give them a short story and they read it the same afternoon.

No one disagrees with brevity. Almost all users want concision. However, writing an article is different from writing a help system. In a help system, I do think almost all the features should be documented — somewhere.

If you limit the help topics to just the core topics, what happens when the power users search for an advanced question and find nothing? What happens when Joe user wants to know how X widget functions? Is our response simply, “Sorry, we didn’t think that feature was important enough to document”?

Fortunately, this whole dichotomy between (a) documenting everything and overwhelming the reader and (b) selecting what to document and risking absent information is an Either-Or fallacy. It is possible to both document everything and give the user a brief guide. Simply, document everything in the online help. Then create a quick reference guide to give to the user.

Am I missing something?

To avoid the disheartened look on a user’s face as the two inch manual makes a thud on his or her desk, reduce your printed manual to a much smaller subset of the online help, rather than duplicating it. Remove all the low-priority topics. Let the reader know that full documentation is in the online help.

Since users don’t typically read manuals anyway, they’ll welcome this approach. No one has ever said to me, Tom, this guide feels a little thin. Couldn’t you add more to it?

Fowler’s advice to avoid documenting everything may reflect what he was documenting as well as his time. Fowler was documenting code, which has layers upon layers of depth. But he didn’t say to leave out documentation, just to “leave the details for the code.” You can add little notes here and there in the code using slashes.

Also, Fowler wrote his article back in 1997 — more than 10 years ago. At that time, I’m not sure he had all the single-sourcing capability we currently have. Perhaps producing subsets of documentation (or multiple manuals for different roles) was too difficult.

I’d be curious to hear your approach. Are you over-documenting? What’s your approach to reducing the “thud” while still delivering complete documentation?

Additional Resources

Listen to this Boagworld podcast for details on agile methodology.

Read this post on extreme technical writing from a tech writer’s point of view.

Interesting Technique for Discovering Software Changes and Building Rapport with developers

Tom Johnson — Sat, 15 Dec 2007 06:39:57 +0000

You know the typical scenario — the technical writer is the last one to be notified of changes to the application (be it interface or functionality), and developers hate reviewing the manuals we write. Recently a business analyst explained an interesting technique to me for not only discovering software changes, but also building rapport with developers.

He said that in a previous company, he bought all the technical writers video cameras that record directly to DVD. In order for developers to mark a feature as complete, they had to demo it for the tech writer. Since engineers love to demo what they’ve just built, it was a welcome event — a triumph in which the developer gets to show off his or her genius.

So the tech writer goes to the developer’s machine and starts recording, aiming the video camera at the screen while the developer explains the new feature and shows how it works. Sure, video of computer screens is never very good, but he said it was visible enough.

Using this technique, tech writers learned first-hand the new features and captured them directly. With this footage, they created accurate documentation and the Quality Assurance team also used it to build test scripts. The developers never had to review any written documentation — their review was simply the demo and video footage.

I’m eager to try this out. Has anyone had any experience with a technique like this? Can you suggest a better technique?