- By Michele Marques, Lead Information Developer, ITSM

I entered the competition because:

• This was a new manual - everything good (or bad) about this manual was my responsibility. Many times, I work on manuals that have other contributors - or that originated with previous authors.
• I wanted to find out how my documentation held up to international standards.
• I wanted to get feedback from technical writers outside my organization.

I ended up winning a merit award. It felt great to get award and feel validated for my work. But the feedback was especially helpful. People from outside my organization had a different take on what works and what could be improved. Today the guide is better than ever.

I'm fortunate to work with a team of writers and editors, but for a lone writer, the competition might be your best opportunity to get feedback from experienced technical communicators.

- By Michele Marques, Lead Information Developer, ITSM

• Video - showing the product in use
• Interactivity - using Flash or other technologies to add tutorial    elements
• Wikis and discussion forums - enabling customers to collaborate and    share information
• Proactive assistance - offering information for the current task,    without the need for the user to click a help link
• New devices to display information, such as PDAs and mobile    phones

I'm sure that there are other cool ways to provide information to users. Do   you have any examples of other ways to provide information?

Cool doesn't necessarily mean useful

As our users spend more time on Web 2.0 sites and checking web sites on   their mobile phones, does this change the way that they need to receive   information when getting help on software products? Do people who've grown   up on YouTube read manuals or online   help topics?  If not, perhaps we information developers need to adapt   to the new paradigm.

But to determine what's really useful, we have to look at what our users   need, whether in  manuals, help, or other product information. Where do they get stuck?   How do they process information? How will they find the information that   we're providing?

On   Palimpset, Sarah blogged that she has recently joined Facebook and mused whether Facebook could be used for technical support or other technical communications.

I started wondering what documentation might look like on Facebook or other social media. Currently, most documentation is the equivalent of Web 1.0 - printed manuals, PDFs, online help, and other forms that present useful information, but don't allow users to reorganize the information, to add to it, or to communicate. Communications with users are typically handled separately from documentation.

What might documentation look like on the Facebook platform or other social media (Web 2.0) platforms?

What is salient about Facebook for documentation?

On your Facebook profile, information is presented in modules. These modules are typically small, although some expand to fit the content. As a user, you can control which modules to display, as well as their location on the screen.

Facebook provides space for you or others to write ("the wall"). Additionally, many of the modules provide space to add comments. Notes can be used for longer, article-length pieces of information.

On a user's profile, Facebook lists some of the user's friends, along with a link to display all friends.

How are these features relevant to documentation?

Information modules aren't new to technical writing. They're a key aspect of Content Management Systems, and have really taken off with XML and DITA. If we are using Facebook as a model, these information modules, would mostly contain small chunks of information, although some would expand for the needed content.

The user would be able to control which types of modules to display, and where to locate them on the screen.

Users would be able to annotate the documentation. These might be comments added to individual topics. If this were help on a multi-user system, each screen would have a place for messages, which could be a forum for adding tips or asking questions.

Facebook is about people; the friends displayed are part of the user's social network. For documentation, instead of friends, a list of related topics would be listed. If the list were over six, six topics would be listed, with a link to the complete list of related topics.

Can you give an example of how this might work?

On Facebook, your profile is centered around you, the user. Everything is about you and your friends. For documentation, we must find another starting point. For example, if Facebook-like documentation were provided as a help system, the starting point could be the user's screen when clicking Help.

Information modules might be available to:

• List all tasks that can be performed on the current screen (with links to more information about the tasks)
• List all tasks that include the current screen.
• Describe the purpose of key fields on the screen.
• Provide keyboard shortcuts, or other sorts of accelerators.

Notes would be available to present concepts and procedures relevant to the current screen.

A list of related tasks would be available.

The user could writer on "the wall" to write notes to himself (or other users) about the current screen, and to pose questions that other users (or someone in Support) might answer.

Does this seem like too much information to fit on one screen?

Perhaps. But if the system is as configurable as the Facebook profiles, the user can remove any modules that he doesn't want to see. Also, he can arrange the modules in any order or column, so that the overall layout meets his needs.

What about other social media platforms?

What about them? What do you think documentation would be like if it used a platform based on Myspace, LinkedIn, or twitter? Does Facebook inspire you in a different way?

If you have your own vision, write it up in your blog, and leave me a   comment. I'll post a round-up of the entries.

More and more developers are moving to Agile. As a result, information developers and technical writers are struggling with the best approach to creating documentation in an Agile environment. We don't want to write too much too early, for fear we will have to rework the document, as features change in subsequent iterations.

Anne Gentle blogged   about creating a Documentation Plan in an Agile environment. Her approach is to keep the doc plan high-level, and not get into all the details. My approach is to include updates to the doc plan in the schedule.   I plan to work on the most solid features first, and update plans with each iteration.

One great suggestion from Melody Locke is to include documentation in the acceptance criteria. I like this suggestion regardless of the development methodology being used. If documentation is truly part of the product, the product isn't complete without appropriate and accurate documentation.

I'm still fairly new to agile. But I like getting feedback from customers early on. When we receive customer feedback in the early stages, it's easier to make adjustments. When I get feedback on the documentation, I have time to make the guides better serve the customer's information needs.