Tag Archives: minimalism

wiki

What are wikislices? How can I try wikislicing?

I’ve had a very serendipitous journey lately based on my podcast on TechWriterVoices and the work on the One Laptop Per Child project that I want to share. Through others listening to the podcast, hearing about OLPC, and contacting me via my blog, I learned about wikislices, and it just might be a method for DITA and wiki to play in the same sandbox.

This concept seems very apropos to the shift we’re seeing in technical publications away from books. What’s interesting is that there seems to be two directions you can go from books – wikis or DITA, crowdsourcing or singlesourcing. Some times it seems like choosing between wikis and DITA is like new school/kewl kidz versus old school/squares.

But what if there’s a way to have your wiki be the single source (also crowd sourced but with a strong guiding hand, let’s say), but to create cross-sections or wikislices of that content? This idea would essentially allow writers to write in the wiki and then either the writer or an architect would “slice” it.

There is a way to Wikislice Wikipedia already. Go to wikislice.webaroo.com and enter a subject. You can view this nice slideshow showing the basic features of a wikislice. You can even make offline wikislices available.

There are selected wikislices created already for the One Laptop Per Child project, such as the Great Wall of China, Space exploration, and the Brothers Grimm.

What’s interesting to note is that the Webaroo wikislice of “violin” is different from the one for the OLPC wikislice of “violin” and it appears that the OLPC one is more easily read by a student. Somehow the slices are customized, perhaps for the audience? I’d like to dig deeper into the guts of a wikislice. All I’ve found so far is that they’re built using regular expressions according to the Wikislices definition on the OLPC Wiki.

With the correct use of tagging in your wiki, I would imagine that you could slice the wiki based on audience, language, or content type, such as grouping tasks, reference, or concepts.

It seems like any wiki could be wikisliced, and if DITA maps are the method for the slicing, then you can get a table of contents and PDF output based on a cross-section of your wiki – a wikislice. This process is just a thought piece right now, but my hope is that working on the OLPC project helps perfect the wikislicing process so that it could be used for other end-user documentation projects.

writing

Who else wants to be a technical communicator?

I have been reading many essays and articles lately about “where has technical writing gone” (including a nice reaction countering the manual-less existence Jared Spool perceives) and “woe is technical writing.” Okay, I made the last one up.

But all of this reading and other recent experiences has made me think about the core competency of writing and writing well. Avi commented in a previous post about how our (writers’) business case and value-add is that others don’t want to write or are not as good at it as we are. One conclusion is that we should know our core competency and stick to it.

But does sticking to writing as a core competency work in the age of self-publishing?

Others are asking and answering this question. I found the article “Is the Net Good for Writers?” a though-provoking piece. Especially this quote from Clay Shirky pretending to write in response to whether Herr Gutenberg’s new movable type is good for books and for scribes.
In the same way that water is more vital than diamonds but diamonds are more expensive than water, the new abundance caused by the printing press will destroy many of the old professions tied to writing, even as it puts in place new opportunities as yet only dimly with us.

It’s a long article, containing well-written and dense prose – which is exactly what some of the contributors say the Net doesn’t value. My takeaway is that your goals as a writer will dictate your reaction to the net’s value to writers. Is your goal to be paid, and paid well? Then the net might be watering down the market (supply and demand). If you goal is to make connections, then the net offers opportunity that might never have been available in the day of the printing press’s invention.

I also think of the US-based screenwriter’s guild threatening a strike because they are not getting paid every time someone views a Season 2 DVD of an entire season of shows, or downloads a show on iTunes and watches it on their train commute on their iPod video. The writers didn’t come up with the idea of watching a TV show on a handheld device. Their core competency is writing. And we all know deep down that the best shows are the well-written ones. So how can our profession learn from the screen writers guild? Learn that good, fast, high-quality writing is valuable. Learn that a voice and consistency is important, though subtle.

The Society for Technical Communication recently worked with the US Department of Labor to to update the job description for “technical communicator.” Susan Burton discusses it in her Intercom letter You May Already Be a Technical Communcator! Now I won’t jump into the STC forum discussion about this particular word choice, substituting communicator for writer, but it is part of what I’m trying to parse out for my own professional job description and also describe what I like to do and what I’m good at.

I’m also thinking about minimalism and how to achieve it with writing alone. I am beginning to think that it can’t be achieved with writing alone. You probably need a team including a designer and illustrator to communicate the minimal message, and probably an information architect. As Bill Gearhart says, the Lego documentation is a gold standard of minimalism. But there is so little writing that I wonder where my value add would be in trying to emulate this minimalism? I’m not a designer or illustrator. I need a team to support the writing value that I offer.

I think the title of this post could be “Who else wants to be a designer?” And the answer might be, “technical writers.”

DITA wiki

Are structured authoring and wiki opposing forces?

It was one of those light-bulb-type discussions. Ideas popping and synapses firing. I had lunch with Chris Almond and Don Day this past week, discussing the potential authoring of wiki articles using DITA. We went through possible workflows, from a web-based DITA editor – to authoring in another tool and merely using DITA as an intermediary and transforming to wikitext.

If you know about DITA, you recognize Don Day as the chair of the OASIS DITA Technical Committee. Our lunch companion was Chris Almond, an innovative forward-thinking project manager. From him, I got the sense that internally at IBM, there is a perception of DITA as a technical writer-only tool to have in your toolkit. Chris coordinates and manages the authoring of IBM’s RedBooks, a very popular and technical set of documentation that are not product documentation but rather they show users how to implement a specific set of products, integrated together. He’s coordinating teams to do the scenario-based writing that applies the product in real-world situations. Many techpubs teams are striving towards use cases and scenario writing, and RedBooks are a great model for how to do it well. I know we tried to emulate it at BMC Software, and Bill Gearhart has an article about “Scenarios and Minimalism” in the CIDM Newsletter that discusses scenario and case study authoring.

Chris is trying to figure out how their current writing methodology and processes can be protected but also enhance the tools used and improve the resulting connections after the deliverable is written. Currently they engage with teams of authors to outline scenarios using mindmapping software and then divide up the actual writing assignments according to the author’s experience with the scenario. I immediately thought of JoAnn Hackos’ and Dan Ortega’s suggestions to have field personnel contribute scenarios to a product’s wiki when Chris described their process.

How do you actually empower the teams to write these wiki articles and assemble them into a useful (maybe book-like) wiki? Another question to Chris was, how do you layer an outline or table of contents on to the wiki, and then test and fold in any changes that wiki contributors make?

After at least an hour discussion I’m not sure we ever came up with the correct toolset. Or rather, there was a toolchain that could be used which is certainly do-able but not the ideal that he wanted to get to. I suppose one ideal is a DITA-based wiki with a web editor interface that would change editor strictness based on the author’s permissions. Authors who knew DITA and were most comfortable writing structured tasks, reference, and concept topics would get an XML-validating editor and authors that preferred more free-form would just use a rich-text editor that was nothing more than HTML headings, paragraphs, and lists underneath like what you use in Drupal, WordPress, or Blogger.

Suddenly it became apparent to me (but I won’t and don’t speak for Chris and Don) that some people are more determined to keep the editing quick and easy, but sacrifice that structuring and vetting step that structured authoring gives you.

This realization gives me a sense that there are two camps in technical documentation. There’s the “quick web” folks who connect easily and author easily, and then there’s the “structured quality” camp that requires more thoughtful testing and time spent on task analysis and information architecture. Also, the types of information that these authors are trying to capture are opposed in some senses. Then I thought a diagram might help.

wiki-fast-easy <-----------+-----------> DITA-difficult-tested

high-level scenarios <-----+-----> detailed dialog boxes

With such an easily diagrammed moment, you’d think I’d have an answer for the process we could use for a DITA-based wiki. Unfortunately it’s not quite refined, but I feel a step closer to understanding why this process is difficult to create – because the process is paved with these tradeoffs and apparent compromises and decisions you have to make along the way.

agile techpubs writing

Making the documentation cruft calculation more user-friendly

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

agile

Writing End-User Documentation in an Agile Development Environment

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

talk.bmc

An outline for a passionate user guide

From “Creating Passionate Users,” Kathy Sierra follows up to her “let marketing write the manuals” post

Her post on “Creating Passionate Users” is a long one but well worth reading — How to get users to RT*M. Since this is a G-rated blog, apologies for the known acronym. Let’s say it stands for “Read The Fine Manual.”

As promised, I’m following up to my prior post “Seducing users to read the manuals” by taking a look at what Kathy has to say about creating that passionate user guide.

Since I’m currently working on information modeling which means analyzing content especially at the table of contents or outline model, I was excited to see her write a “model” of sorts for a passion-inciting user guide. I see a distinct tie between the structured authoring approach that we’re taking and the user learning and understanding that she describes.

So, what’s in her ideal user manual that inspires passion?

A good manual for a complex product should usually include at least FIVE distinct sections:

Reference Guide - The only way to really make it “stick” is by helping them ‘get it’ on a deeper level, where the mental model (thought bubble) in their head matches the one you were trying to communicate… the mental model that lets them extrapolate and infer and be creative about things that weren’t in the tutorial.

Tutorial - By “tutorial”, we mean walking the user through a concrete example of using the product to do a specific task.

Learning/Understanding - It is up to us to get the user/learner motivated to not just Open The Manual, but to want to actually… learn new things.

Cookbook/Recipe - A Cookbook/Recipe section is where a series of steps that might otherwise live in different places in the manual are all brought together under something like a “How do I…” heading.

Start Here - A “Start Here” section, which many product manuals include, is a low-intimidation way to help the new user jump in and get something happening.

Wait a minute… those sound familiar

If you read the rest of her detailed descriptions of each section, in essence, I believe she’s describing John Carroll’s basic concepts of Minimal documentation. Minimalism was first described by John Carroll as an instructional design philosophy at the IBM Watson Research Center in the 1980s, presented in his book The Nurnberg Funnel (amazon link).

The way I see it, structured authoring has a basis in minimalist principles. Minimalist principles encourage both us writers and trainers or instructors to:

  • get users up and running quickly (Start Here section)
  • let users think and improvise (Reference Guide section)
  • focus the material on real work, real goals (Cookbook or Recipe section)
  • make use of a user’s prior knowledge (Learning/Understanding sections)
  • use error recognition and error recovery as learning helpers (Ah ha! The one item Kathy missed out on but a few commenters noted the omission.)

I have to say that she seems to be describing consumer-product manuals, like your TiVo or MOTORAZR. I personally find it more realistic to get passionate and excited about consumer products than the products that I need to use to get my job done. Frankly, the docs I write are for products that people use to get their jobs done. So… I’m not convinced that her outline works well for the products that I document. Yet… it certainly offers some thought-provoking ideas and also makes me think, how can I work these types of sections into the docs I have? Will my particular audience appreciate sections that have the type of info that she’s talking about? Most likely the answer is yes. Wouldn’t we all like to be a little more passionate about the tools we use every day?

Lastly, be sure to check out the collection of links to her favorite education/learning blogs. Most of those are already on my RSS feed list, but I’ll be adding a few more to my list thanks to her roundup.

elearnspace
Viki Davis: Cool Cat Teacher Blog
Jay Cross: Internet Time Blog
Cognitive Daily
Judy Breck’s Golden Swamp
elearningpost
Usable Help
Darrren Barefoot
Boxes and Arrows
Solveig’s Open Office blog