Greyfiti

A new minimalist principle that John M. Carroll didn't think of - Increase acquisition speed

In my professional engagements, I'm a huge evangelist for minimalism in technical communication. So much so, that I've spent the past 7 months codifying the first publicly available, detailed methodology for authoring in a pure minimalist style. I'll be officially rolling out this guide (for free to all) as soon as possible. It's been mostly finished for several months now, but I've been holding off while fine-tuning some details with an entire hands-on release cycle at my present company, wherein my doc team has achieved the following in a mere six months in an agile environment:

• Completely refactored our authoring methodology from traditional "best practices" to pure minimalism, using a detailed methodology/style guide that provides comprehensive reference and training for new writers.
• Completely refactored our source authoring from traditional siloed FrameMaker and RoboHelp to fully collaborative Confluence.
• Developed a nearly push-button method for exporting from Confluence, importing into RoboHelp, and generating/publishing WebHelp for our product that seamlessly merges our new Confluence-based minimalist user doc with the few remaining legacy RoboHelp projects that we'll completely phase out in the next release.
• And this is for a product whose UI and macro/micro features and functionality is heavily tailored for nearly every customer installation, which is incredibly challenging to document. (Minimalism offers the best answer to this tough problem, and I cover how to do this in my upcoming guide.)

In my methodology, I originally focused on the four main principles that John M. Carroll espoused in The Nurnberg Funnel. (I feel that the few other principles he specifically calls out are just nuances of these four.) Briefly, my paraphrased version of these four all-encompassing principles (with acknowledgements for some other fine luminaries in the field who have expanded somewhat on Carroll's original wording and ideas) are:

• Anchor instruction in the job domain
• Less is more
• Eliminate sequence
• Expect user error and provide recovery instructions

My methodology also calls out two additional principles of my own. I feel that Carroll probably expected that these didn't need to be specifically called out in his original work, because one would expect that these are covered by "best practices" in technical communication. But in my experience, "best practices" are not well-codified at all, and every writer has their own ideas about what that term means. So to reduce ambiguity, I spell them out with lots of detail and examples:

• Reduce ambiguity
• Increase brevity

The real subject of this article is the new principle I'm about to add to my methodology as well:

• Increase acquisition speed

Looking back at the concrete methodology I've developed over the past few years (through a lot of experimentation and iterative refinement on real projects), I realize that this new principle was always a fundamental driver behind my specific methodology and presentation style. What I lacked until now were compelling arguments for why this is an important principle to observe.  Well, a wonderful video created just a few weeks ago has finally been making the rounds in the Social Web, and when I watched it just now, I had a wonderful moment of satori. Spend 10 minutes to watch this video (worksafe) before continuing. At roughly the 7:40 mark, the video points out something that I've blogged about before, which is essentially that most of us long-experienced technical communicators come from a generation that was trained to be comfortable with absorbing information at a much slower pace, and in a much more passive format, than people even one decade younger than us would tolerate. And the folks in their 20s and younger now? Forget it. The typical "best practices" that most technical writers still adhere to are completely out of touch with the sheer speed at which 20-somethings and younger expect to be able to absorb information. I like to think that despite my age, I'm actually more in sync with the reading (or should I say "skimming"?, lol) modes of the 20-somethings today. While that might be wishful thinking, I do pay a lot of attention to any news/research I can find about the ways that kids prefer to learn and engage with information of any sort, which is one of the things that pushed me in the last decade to keep innovating and finding ways to improve on traditional technical communication practices and steered me quickly towards minimalism once I learned of it (15 years ago? Hard to remember now). But as evidence: I've routinely had 4 screens at work for nearly two years now: my MacBook Pro, my iPad (formerly my iPod Touch), and two screens for my company-provided Windows workstation/laptop. I keep the best social aggregators I can find running full time. I wade through a lot of information input every day. I consider email (even company email) to be a nuisance and mostly spam to be checked only a few times per day. (And countless messages go unread if the subject line doesn't scream "I'm important!".) I love Campfire and loved Google Wave (even though they blew it) because to me the concept of "centrally-hosted conversations" is so much more efficient than the tired old paradigms of face-to-face meetings and point-to-point communication shuttling. Where am I going with all this? I feel that I fully understand the critical importance of evolving our technical documentation in any direction that increases the acquisition speed of the specific information that readers are seeking when they crack open our technical documentation. The old paradigms for writing books and chapters that are intended to be read sequentially just have to go. They are epic fail to a near-majority of your current audience, and the full majority of your near-future audience. This means we have to get very creative on three fronts:

• More pervasive use of inline links to enable cross-navigational browsing. It doesn't matter that recent studies seem to indicate that readers retain less information when they aren't forced to read sequentially. The function of our doc is not to teach, but to answer spur-of-the-moment questions. If readers need that same information again in the future, they'll find it that much faster the second time. They don't need to remember it; they only need to remember their strategy for finding it.
• More mechanisms for skimming and scanning for domain-oriented keywords to quickly find the specific information they seek.
• And the reflexive version of the preceding point: more mechanisms for entirely removing systems-oriented language and organization. Modern readers have no desire nor patience to learn your system. Instead, they only want to know how make your system support their immediate domain goal.

As always, I hope you find essays like these informative and useful. I specifically avoid a minimalist style for these blog posts because these are focused on teaching and learning, not giving you quick answers. There will always be a place for more traditional discourse like this, just not in most of our technical communication products. Watch in the coming months for the unveiling of my new, state-of-the-art methodology for minimalist authoring.

Google Wave versus Google Buzz

Confused about how Google is positioning Wave versus Buzz? Me too, until I found this excellent article: Google Buzz Versus Google Wave. Essentially, Wave is for collaboration, while Buzz is for conversation.

Distributed teams can be just as efficient as collocated teams

You've probably heard the opinion that distributed agile teams experience a significant "drag factor" due to the inability to communicate as efficiently as fully collocated teams that are sitting together in the same physical bullpen. This sentiment is held dear by some agile experts, yet when pressed for figures to support this claim they have trouble producing them, and we're told to trust their experience. To be fair, I would have agreed with this sentiment even as recently as five years ago. But technology can advance quite a bit in five years, so this post is an attempt to convince you to shake off this now obsolete notion. Unlike the vague hand-waving that I've personally witnessed, some companies have managed to track measurable statistics regarding distributed versus collocated teams and their results seem to indicate that the popular sentiment is no longer valid. For example, Microsoft recently published a report in the August 2009 Communications of the ACM demonstrating that their empirical data collected during the course of development for Vista indicates that there is no significant difference in the performance of distributed versus collocated teams, and even more interesting, that there is no difference in the number of defects found in the output of distributed versus collocated teams. (Here is another link to a related announcement.) I'm here to back up Microsoft's weighty report with my own empirical observations. The scrum team I worked with for the past 9 months was fully distributed from day one, and within our first two sprints we had managed to find tools and adopt collaboration techniques that reduced the "communication drag" to zero. By the third sprint and beyond, several of us who normally worked together in the physical bullpen often worked from home and the team noticed no "drag" whatsoever. (Two of our members were permanently situated in remote geographic locations.) Not only was there no difference in communication bandwidth regardless of where anyone was working on a given day, but we actually had several occasions to witness that our communication bandwidth was faster than some teams that were fully collocated and did not use the tools and techniques that we did. How was this possible? Because we had successfully created a "virtual bullpen" at practically no cost. And it worked. Beautifully. The following 9-minute screencast shows you how we did it. Tip: If you view this screencast in the embedded player above, it will automatically play in high-definition mode. If you watch this from its source page on YouTube, you must manually enable HD mode.

Concrete strategies for using minimalism in an agile development environment

In my post from last month about Why minimalist documentation is not always a good match for agile development, I explained the issues with using minimalism in an agile environment but was unable to offer any advice on how to effectively use a minimalist approach in an agile shop. I was still wrestling with that question myself. I think I'm now able to answer that question, but rather than do it in an entirely new article, I feel it's more useful to simply add that information to the above-linked article. Having both the challenges and solutions in one article makes it easier to distribute for discussion among your own team members and other stakeholders. So please see the above-linked article for the full discussion. If you've already read that article before today's date, the new information is in the third section, about mid-way down, titled What are the conditions that make minimalist authoring more possible in an agile shop?

Why minimalist documentation is not always a good match for agile development

I've surprised several colleagues recently with my strong opinion that minimalist documentation is not a good match for some, perhaps many, agile shops, and that instead a basic topic-oriented authoring approach is a better fit. In all cases, their response was essentially "But I thought that minimalism was recommended as the best approach for agile?" I can understand this response, given that minimalism itself is not well understood within the technical writing community at large just yet. As this article will explain, the key elements of an agile shop that contribute to how successfully you can author in a minimalist style are how large/complex your product is, and whether your product managers maintain detailed strategic feature roadmaps that guide the prioritization of your product backlog (such roadmaps are not a common practice in agile because they can be argued as being too waterfall-like and therefore anti-agile). A quick review of what minimalism really entails The Wikipedia blurb describing minimalism as it applies to technical communication is good evidence of this general misunderstanding. This blurb is incorrect in several respects: it focuses on "short task-oriented chunks" and then goes on to list DITA as being based on minimalism. Wrong, wrong, wrong. (By the way, I was one of the active OASIS technical committee members that authored the DITA 1.0 specification.) DITA revolves around three specific things:

• Some ingenious and unique techniques for specializing a generalized XML content model into new content models in a way that enables output processing to back-level its processing code to the style and transform rules of the generalized ancestors, if necessary, without "breaking" the output processing.
• The concept and techniques of using special-purpose MAP elements (often referred to as DITA maps) to enable modular reuse of atomic topic-oriented elements in various publishing output.)
• An authoring methodology called topic-oriented authoring, adapted from Robert Horn's Information Mapping methodology, that centers around three main generalized ancestor content models used in DITA: concept, task, and reference.

Note that you do not need DITA to perform topic-oriented authoring, which is merely a conceptual approach that is a simplified version of Horn's Information Mapping methodology. Also note that topic-oriented authoring has absolutely nothing to do with minimalism. I'll elaborate on this shortly, but the main contradiction is that minimalist topics by their nature will mix all possible information types together in the same "chunk" or "block" of text, whereas in Information Mapping and topic-oriented authoring, you are expected to rigidly and artificially separate information type into different blocks. For example, in the DITA world you would not put procedural or reference information into a concept topic or into any topic that was specialized from a concept topic. This rigid topic typing is very easy for authors to achieve and useful for many information-reuse scenarios, but it's actually very reader-unfriendly in many ways and it runs counter to some basic techniques and principles of minimalism. It's probably worth noting at this point that I'm well-versed in minimalist principles. I have designed and authored one fully minimalist user guide for a large, complex software product (Web Content Management for iMIS). I have also been trained in JoAnne Hackos' modern blend of minimalist principles. As a career tech writer with 25 years of experience in the field, I feel that in general, nothing serves end users better than well-designed minimalist documentation and well-designed minimalist product interfaces. Despite this, it's just not feasible to produce well-designed minimalist documentation in some, perhaps many, agile environments. At least not for a version 1.0 of any new feature set or product. To understand my assertion, let's first review the most modern understanding and application of minimalism. If you've read only John Carroll's original The Nurnberg Funnel, you don't have the latest and greatest synthesis and explanation of the principles of minimalism. Instead, you should read Minimalism Beyond the Nurnberg Funnel (MIT Press). If you don't have immediate access to this book, the following paper presented by JoAnn Hackos at the German HCI conference, Softwware-Ergonomie '99 is a concise summary of modern minimalist principles. (As an aside, If you are a technical communicator looking for hands-on training in adapting these principles to the development of user documentation, I highly recommend the courses offered by JoAnne Hackos' company.) An Application of the Principles of Minimalism to the Design of Human-Computer Interfaces The two most applicable principles of minimalism as it applies to user documentation are as follows:

• Your documentation (and product interface and workflow) should be anchored in the task-oriented domain of the user. In other words, everything you write should be organized and grouped and labeled around a detailed task/work analysis of your target audience and the business processes/goals they are using your software to help them accomplish. Minimalist documentation is not just task-oriented. Instead, it is domain-oriented. You can write reams of task-oriented documentation that has nothing to do with the user's domain that they use your software to support. Instead, you end up with topics that describe how to use each feature of the product. In the tech writing profession we often speak of "task-oriented documentation versus feature-oriented documentation", but the simple truth is that those are not opposing things: task-oriented documentation most often revolves around the granular features of the product and the interface organization of the product and the workflow of the product.
• Your documentation (and product interface and workflow) should support exploration and self-learning rather than prescribing cookbook procedures for everything. Users always try to use your product in ways you never intended or envisioned. Users all have their own unique mental maps and learning styles and in general learn better when they synthesize their own understanding of how to make your product support their business goals. So in minimalism, you don't prescribe how to do something. Instead, you support typical user patterns of self-exploration within the context of trying to use your software to accomplish a domain-oriented goal.

The net result of these two essential principles of minimalism is that while your topics might look task-oriented on the surface (because their headings are phrased in terms of typical domain-oriented user goals), the content of any of these topics will end up being fairly light on procedural steps and instead heavy on a deliberate mish-mash of concepts, principles, and reference information that attempt to anticipate the questions and problems the reader will have when exploring the product. For any given domain goal "How do I accomplish business goal X with your product", you might need to describe the high level pattern of navigating through several features of your product (a workflow, if you will), anticipate and describe the gotchas and stumbling blocks they might encounter, and most importantly provide them with the essential concepts and details they need to synthesize their own specific answers to questions they have about wrestling your product to accomplish their domain goal. Being too prescriptive and writing a cookbook feature-oriented procedure constrains the thinking process of both the reader and the author. A well-written minimalist user guide teaches the reader patterns and principles for using your product to achieve their domain goals. Each typical domain goal is the focus of a topic or topic cluster. Within that topic cluster you enumerate the general workflow pattern and you describe the principles and concepts and details needed to support decision making and problem solving they're likely to encounter in the course of figuring out how to achieve that domain goal with your product. Also important is the fact that each such topic/cluster will purposefully omit all the other details that simply aren't germane to the domain goal focus of the topic cluster (or that you could reasonably expect the majority of your target audience to already know or understand). For example, you might have feature X of the product that is used in the process of accomplishing three different domain goals A, B, and C. For goal A, you need to know things about feature X that simply aren't relevant to goals B and C, and similarly for goal B you need to know things about feature X that aren't relevant to goals A and C. In a typical topic-oriented information architecture, you'd have some monolithic conceptual topic(s) or even an entire conceptual chapter (such as "security administration") that you conveniently hyperlink from your nice concise cookbook procedure for defining a widget. But this provides an overwhelming amount of conceptual information that isn't relevant to the one domain goal the reader is trying to achieve. (And studies conclusively show that very few reader types are motivated to wade through any amount of conceptual information so the more you can break up all the complex concepts and spoon feed them as needed ensures better uptake of your conceptual information.) Finally, all of these information types are organically intermingled within each section of the topic--there's no artificial separation into some publishing-system-friendly notion of modular, reusable information types. All of the preceding is an ideal case. In some situations, your authoring system might hamper you from achieving this ideal. For example, in the Web Content Management guide that I linked earlier in this article, I had to compromise to some degree on all the typical field reference information. If our product allowed a context-sensitive help architecture at the field level, literally all of the information in my various "Fields:" topics would have been in the product UI itself and not in the user guide. But since we were constrained to put field reference details in the written user guides, it rarely makes sense to duplicate atomic field descriptions in numerous topics unless your authoring system supports that degree of embedded object reuse (otherwise you have a maintenance nightmare on your hands). So in my case I had to compromise on all the field reference info by at least grouping the field definitions under topic headings that were object-centric rather than window-centric. In other words, if you're looking at any product window dealing with content records, there's only one topic to go to within a small set and it's obviously named (and search-friendly) as "Fields: content records". Why a minimalist authoring approach won't work for many user stories Alright, so now that we've highlighted what minimalist documentation is really about, why isn't this a good match for an agile development shop? After all, aren't those user stories written from the perspective of a user goal firmly anchored in the task-oriented domain of the user? Doesn't each user story suggest the nucleus for a perfectly usable topic in a minimalist user guide? After all, stories are phrased thus: "AS A (user type) I WANT TO (domain oriented goal) SO THAT (domain oriented benefit to the user)" No. For one simple reason: most user stories are typically too granular. User stories that get pulled by an agile team have been broken down into some unit that is small enough for the team to accomplish within a short sprint cycle. Most of these user stories are either implied or explicit "chunks" of a larger "epic" user story or sometimes an even larger "theme" user story (comprised of epics). Your product owners and teams involved in writing good user stories for the product backlog might not always consciously realize that most of the user stories on your product backlog are effectively small, granular parts of a larger whole, but that's usually what they are. The point being that in any one sprint, while developing functionality for any one user story, you very often don't have the big picture view of the entire "real" domain goal that this story will help your users solve. It might take several teams several sprints to finally complete all the granular stories that really deliver the entire epic or theme, and it's that epic or theme that is the entire picture of some domain goal that your users want to use your product to help them achieve. As an example of this over-granularity of user stories, let's take one of my favorite collaboration tools (EtherPad) as an example. At one point, EtherPad did not have a feature to show visible line numbers. So at some point, a user story that ended up in their product backlog was probably something like:

AS A collaborative author, I WANT to optionally see line numbers in my EtherPad SO THAT I can verbally direct my collaborators' attention to a specific line for discussion regardless of how long the EtherPad is becoming.

In this example, I ask you how that new feature and its granular story in any way constitutes a user-centric domain goal for collaborating with EtherPad? By itself, it's too small and too granular to be anything more than a basic, intuitive aspect of collaborating with EtherPad. When this feature is added to any minimalist documentation about EtherPad, it would be nothing more than a sentence or a bullet list item in a small section that describes some useful ways you can tweak the behavior of your EtherPad in a much larger topic about actually achieving some typical domain-oriented goal with EtherPad. What if this domain-oriented goal wasn't really visible or clearly understood by anyone (especially the technical writer on an agile team) until many sprints later? What if it wasn't until this new line-numbering feature and several other features that all contributed to making a very long EtherPad easy to talk about and navigate verbally over voice comms all came together and it finally became obvious EtherPad could now help users accomplish some entirely new domain goals, such as sprint planning? Which of the two following topics is ultimately more useful to your customers to document?

• "You can now use EtherPad to supercharge your sprint planning, especially among distributed agile teams, and here's how" or,
• "You can now turn on line numbers and here's the procedure for doing so"

Crafting well-designed minimalist documentation requires you to see the 35,000 foot view of your product's features and how they work together to achieve domain goals for your users. You simply don't have this view in some, perhaps most, agile development shops until you're at the end of a full release cycle. By this point in the release schedule, it's extremely rare that the tech writers will have the time and bandwidth to go back and transform the "finished user doc" from each sprint into a truly minimalist presentation. Instead, the best you can hope for is the ability to add doc-oriented user stories in the subsequent release to spend time transforming the non-minimalist topics from the previous release into something more minimalist. In other words, user stories to transform your v1.0 user doc into a v2.0 format that is more minimalist. Unfortunately, few of us would ever be able to justify spending team capacity on doc-oriented stories like these, especially if writers on a team are also expected to perform non-writing tasks and spend all of their capacity each sprint staying focused on tasks for the stories in that sprint. So I'm sorry to say that in some, perhaps many cases, well-designed minimalist documentation is only possible in waterfall development shops that produce huge, detailed functional specs with mock-ups of how every feature will look and how process workflow will behave. Only with an up-front 35,000-foot view of the final shape of your product can you talk to your product managers and customers and salespeople and ask them who will be using the product, what domain goals they have, how they think of their work, and most importantly how all these features and workflow that you can point at in the functional spec would need to be used to achieve those domain goals. As I've detailed in my Evolutionary Documentation post on this blog, agile development forces your user documentation to grow and evolve alongside the product features as they evolve. While it's less than optimal for the end users of our products, the only feasible way to deliver "user doc ready to ship" at the end of every sprint in an agile environment is by authoring discrete feature-oriented topics, one granular story feature at a time. In this environment, feature-centric, topic-oriented authoring is your best approach to meeting the definition of done for each sprint. What are the conditions that make minimalist authoring more possible in an agile shop? Now, before anyone jumps in here and argues that "yes you can use minimalism in an agile shop", remember that I've qualified my assertion with "in most cases...". If your product is small enough, your product managers maintain detailed high-level feature roadmaps, and your product owners really focus on fleshing out one major epic/theme at a time, it might be possible deliver finished minimalist topics at the end of each sprint. This is a lot of "ifs" but let's examine how this would ideally play out.

1. Your product managers (or business analysts, etc) maintain detailed strategic roadmaps of features planned for upcoming development. Each such roadmap clearly revolves around enabling your customers to acheive new domain-oriented goals with your product. Most importantly, these strategic roadmaps are visible to all product owners and agile team members at all times.
2. Each such roadmap is broken down into user stories at the theme and epic level and these theme/epic stories are clearly documented in each roadmap.
3. Your agile teams and product owners work together to break down the epics into user stories that are granular enough to accomplish in the span of single sprints, but every such user storie is clearly tied back to its parent epic in a way that enables every team member to trace any story they're working on back to its parent epic and theme and strategic roadmap.
4. Most importantly, your product owners ensure that all the stories that compose an epic are finished as quickly as possible, and all the epics in a theme are finished as quickly as possible, so that everyone is effectively working to "pull an entire theme" from the product backlog and "work that entire theme to a 'done' state" as quickly as possible. No getting sidetracked and only half-finishing a theme by the next release date!

If your agile shop can actually maintain this type of domain-goal-oriented focus in each release, the tech writers have a good shot at incrementally building out a true minimalist topic/chapter/guide from the ground up through each successive sprint in the release. You can still meet the goals for "ready-to-ship" user doc at the end of each sprint by using the following techniques:

• For the first story that relates to a new theme/epic encompassing a minimalist topic center, Set the framework for the topic by expressing the domain goal that is identified in the feature roadmap and the text of the theme/epic. You're effectively setting up an empty "framework" or "template" topic and adding only the text that describes the domain goal that the topic supports.
• In this first story, your team is building out one feature among many that all work together to support the domain goal that the topic supports. For this sprint, flesh out your topic with the information about this one feature that "fits" the context of the topic. And here's the important part: act as if this one feature is the entire way that your product helps the user achieve that domain goal, even though you know that more features are going to be added in subsequent sprints that actually change how you would use your product to achieve that domain goal. At the end of the sprint, you have a minimalist topic that squarely addresses a specific domain-oriented goal and it accurately describes how to use the new feature from this sprint to achieve that goal. Granted, an end user at this point might go "What? That's it? Your product doesn't really do much to help me achieve my goal" if the product were actually shipped at the end of this sprint, but that should be a rare event if your product owners are working carefully to ensure that entire epics/themes are built out before your next release date (or at least that each epic/theme is mostly built out).
• In the next sprint, you pull another story from that same epic/theme, so you go back to that topic and revise it to include everything about this new feature that is germane to the domain-goal of the topic. Again, the key is to wrap up the topic as if the first feature you documented and this new feature together compose the entire way that your product helps the user achieve that domain goal. Never leave any obvious holes or "To be authored" placeholders in the topic. Always assume that none of the other stories/features you know are still left to be done will actually get pulled and built out.

This iterative, evolutionary approach can help you build your user guides from the ground up in a minimalist style, while still meeting a strict "definition of done" for the user doc at the end of every sprint. But again, this is only possible if your product management and your teams are working from some fairly detailed strategic roadmaps that are similar to the type of detailed functional specs you find in a waterfall shop at the start of each new release. Which some agile shops would argue isn't an agile approach. So what's the fallbackback approach if you don't have this ideal environment? In this case, your only real approach is to develop all new documentation in two major phases:

• Phase 1: In the sprint where a new feature is built, document it in a topic-oriented, feature-oriented way (because there is no domain-oriented big picture to see at this point). Your procedure topic is named something like "Turning on line numbers in EtherPad" (feature-oriented) instead of "Scrum Planning with EtherPad" (domain-oriented).
• Phase 2: In some much later sprint (or possibly even in a subsequent release), when the domain-oriented applications of this feature and other related features have become clear, you put documentation stories on the backlog that say something to the effect of:

  AS A (domain-oriented role name) I WANT the user documentation topics for features A, B, and C to be revised into a minimalist topic describing how to achieve (domain goal X) SO THAT I can clearly understand how the product provides value in helping me acheive my important domain goals.

One final note: minimalist documentation is not faster or easier to write As a final observation, I want to address another tangential fallacy about minimalism that I often hear repeated. It is not faster or easier to write minimalist documentation. In fact, it requires much more skill and craftsmanship to author minimalist documentation. In the case of my Web Content Management guide, the background was that we had an old product using Cold Fusion technology that we were replacing with a new product using ASP.NET technology that was better integrated with our core product and which set the stage for easier 3rd-party extensions. Overall, the general domain goals supported by the new version of the product were essentially the same as those supported by the old version of the product. The original user doc was written in a more typical topic-oriented manner that was very product-centric instead of domain-centric. It was 504 pages long, spread over two books that were titled (and organized) around the two different products that together delivered our total Web Content Management solution. My minimalist documentation for the new version of the product was a single book titled Web Content Management (the domain it supported) that was 136 pages long. That's literally 25% the size of the original two books. The new book was hailed as "unpredecented" by one of our VARs demonstrating the new product at our annual user conference shortly after its release. However, it was hell to write. And it took just as many hours, if not more, than it took to write the 504-page epic that it replaced. Why? because writing in the minimalist style is much more difficult. You are constantly making very hard choices about what's relevant and what's not, and you have to become something of a junior domain expert just to be able to ask yourself the right questions as you're writing it. Anecdotally, at one point two writers were asked to help out by authoring a few of the easiest task-centric topics. They'd had multiple internal presentations about the style and structure of this minimalist doc structure that we were essentially trialing and fine-tuning with this product. They had access to detailed "fill in the blanks" topic templates. They had access to fully completed topics to model their own work against. One of them nailed the style and appropriate content depth. The other didn't even come close; what they wrote was much more traditional and required complete revision on my part. I'm not knocking that writer--they're a strong writer. It's just that they had other priorities and things going on and they weren't getting the hang of minimalism right on the first try. It reminded me of my similar experiences trying to teach a department of writers how to "think" in terms of Information Mapping once upon a time--some folks really had trouble grasping the concepts and techniques. One experienced contract writer even flat out refused to do it, saying it was "a stupid approach" after they became frustrated. So the point is that minimalism is about improving the end-user experience and removing all the bloat that our more typical authoring methodologies produce. Minimalism is not about speeding up the authoring process or making it easier in any way. Quite the opposite.

Google Wave changes everything you know about agile collaboration and technical documentation

Just a few days ago, on Thursday, May 28 at the Day 2 keynote address of Google I/O in San Franciso, Google made history with their 90-minute Google Wave Developer Preview session. Here is a link to the video of that presentation, and in my opinion it will be among the most valuable 90 minutes you can spend this year to watch this. I've never been a fanboy of Google and I personally use none of their tools and products so far except for their search engine and Google Maps, but Google Wave is just brilliant, spectacular, and groundbreaking. Note that I said "Google made history" and not "Google made web history". Google Wave is ultimately going to change the entire face of the emerging Social Web, so it affects every individual and organization that relies on social networking for their information sharing and marketing. Beyond the obvious impact on the Social Web, Google Wave is also going to change aspects of every business that currently relies on communication and collaboration tools of any sort, including the ubiquitous but lowly email. Finally, since this is a blog geared towards technical communicators and agile developers, Google Wave is ultimately going to change (and vastly improve) how every agile team works together and how technical writers collaborate with their subject matter experts, reviewers, and editors. I'm tempted to say "just watch the video and you'll see what I mean", but I know some readers might need a little more convincing to spend 90 minutes watching a video about work-related stuff. Also, I don't want to shock you by writing an article that is only two paragraphs long. ^.^ So why is Google Wave so historic? These are some of the impacts that occurred to me while watching the video:

• Waves are going to become the underlying format of every social networking site that wants to survive. Seriously. Even FaceBook will become irrelevant very soon if they don't adopt Google Wave with open arms. The entire question of FaceBook Connect versus OpenSocial has just become moot. The question of Twitter versus FaceBook or MySpace versus FaceBook or anyone versus anyone else has just become moot. Google has figured out a way to "win" the entire battle for the Social Web in a way that doesn't directly compete with any existing social network, yet makes Google the center of all social networks (that want to survive). The great part is that any social network that embraces Google Wave will become a much better social network. Google Wave will put an end to all the walled gardens. Any social networking site that wants to remain a walled garden will be left out in the cold and suffer a corresponding demise.

• Waves are eventually going to replace email as we know it. Microsoft Exchange/Outlook might be able to hold out the longest because they have the majority of the business market at present, but eventually even the people who work in non-technical industries are going to start doing end runs around their own email system and using one or more implementatons of Google Wave for their internal and external communication. If Microsoft is smart, they too will incorporate Google Wave into Outlook and HotMail, Yahoo! will incorporate Google Wave into Yahoo! Mail, and every other player in the email business will do likewise.

• Google Wave or some more focused/extended implementations based on the open source API is going to supplant (or provide significant new functionality within) pretty much every planning and collaboration tool you currently use for agile. When you watch the video demo link, pay attention to the segment that demos the "Polly" robot. Notice how similar that is to the basic flow of a task board? Some smart developers out there are going to create the perfect (and inexpensive) all-in-one agile support tool using Google Wave before too long. You can use Waves as the basic foundation for performing effective sprint planning, managing your task boards, automatically creating burndown charts from the state of tasks on the task boards, writing/estimating user stories (even integrating seamless "planning poker" functionality), and of course doing any manner of collaborative authoring in a way that prevents all the edit-locking issues of most wiki engines or older Web CMS engines and provides all the speedy real-time collaborative editing features of excellent tools like EtherPad.

• Google Wave will ultimately also change the tools that technical writers use, and the way that they collaborate with their subject matter experts, their reviewers and their editors. Most tool used by tech writers are currently siloed. You can't afford to license people outside the information development department, and you probably don't want anyone else tromping around in your source environment anyway. Collaborative authoring, especially in the high-bandwith mode required by tech writers in an agile shop, requires the painful process of doing your initial collaborative team authoring in a wiki or wiki-like Web CMS or proprietary knowledge management tools like Microsoft Sharepoint, and then manually copying the finished drafts from that external system into the system you use for publishing your information products. Even if you've devised a way to automate moving information between a wiki and your publishing environment (no commercial tool currently does this as a turnkey feature), there is still a fair amount of development time and ongoing overhead in the process. The smart tool vendors for tech writers will be making life easier for themselves and their customers by using the open API for Google Waves to incorporate Waves into their authoring/publishing tools sooner rather than later. The tool vendors that refuse to do this will suffer.

• Alternatively to the preceding bullet, some smart wiki engine developer or Web CMS developer will make the wiki/CMS that finally supplants the traditional tools used by tech writers. They will do this by making Waves an alternative core page/article type in their system, adding more extensive content tagging and/or styling options, adding some ditamap- or AuthorIT-style structures for reusing Waves in various "books", and creating the push-button ability to take a "clean view" (all comments in the wave are hidden) of any Wave in the system and push (and link) it to a standard page/artcle in the wiki or CMS. End-users of the page/article wouldn't be able to directly edit or comment in-line like you typically can with a Wave, but they could follow a link or page control to see a sanitized version of the original Wave that was used internally for authoring, and they could begin comment threads in that sanitized Wave to provide feedback. The possibilities for expanding the current core editing and publishing functionality of existing wiki and Web CMS engines is staggering. I could easily see a wiki or Web CMS that has embraced Google Waves being able to support the authoring and publishing needs of information development departments. Each Wave is just an XML file at its heart, so all you would need is to create some good canned XSLT-based system to output any required PDFs or Word documents or other downloadable/printable information products in addition to the online output of the wiki/CMS itself.

Excited yet? I sure am. I want someone to build the type of tool I described in the last bullet.

Evolutionary documentation

Today I was at a local STC networking lunch and was pleased to see how many of us tech writers present were working in Scrum environments. Even better, everyone I talked to was an embedded writer on their teams instead of being a support writer for several teams, as I know some companies try to do with their tech writers. One person who had read a lot about Scrum but hadn't yet worked in a Scrum environment asked some questions that I think all of us have asked before we got involved with Scrum (paraphrasing): "How do you write documentation when you can't see the whole picture until many sprints have passed? Each story is such a small unit of functionality... How do you plan your user guides? How do you write procedures that use several features in sequence?" The answer is incredibly simple. In a Scrum environment you develop your user assistance (documentation, in-product information support, training materials, etc.) the same way that the teams build the product features themselves: in an evolutionary manner. Just as the developers have to stop thinking in terms of writing monolithic design specs for a release and then trying to develop the features as described in the specs, we tech writers have to stop thinking in terms of monolithic user/task analysis and documentation plans that we then use as a blueprint for developing our product documentation. Instead, every aspect of the product is developed in an evolutionary manner, iteration by iteration. In sprint 001 you deliver a few stories. Some of those stories will create new functionality in the product and there might be a few topics you author to explain that new/changed functionality. There's not much in the way of "glue" topics that you can draft at this point: just some basic procedures, reference, and (maybe) some concepts and principles to describe the atomic bits of functionality that your team developed during the sprint. If you're building some completely new product, there's nothing that looks like a typical user guide yet. Just a miscellaneous handful of topics in a quick and dirty user guide "shell" just so you have a way to publish the documentation you've created so far if you were to hypothetically sell a new release based on what all the production teams have built so far. Remember, one aspect of Scrum and agile methodologies in general is that at the end of every sprint (iteration), you should ideally have a releasable product. So some kind of publishable "user guide" at the end of every sprint is essential. Granted, you typically don't produce a formal beta or gold release without doing some "hardening sprints" that involve a lot of acceptance testing and bug fixes, but the point is that you should generally have a new product version at the end of every sprint that is nominally ready to ship at least as working alpha code that passes unit, component, and system tests (which can all be automated as part of your continuous integration process). So in sprints 002 and 003, etc. you are delivering more stories and their attendant atomic documentation topics. At some point, you realize that enough of a big picture is emerging that you can start filling in some of the conceptual and procedural blanks. Maybe you even start writting and submitting user stories to capture some of the meta procedures that require navigating through several features of the product. Or your product owners or other team members start seeing the big picture that is emerging for the release and submitting such user stories to ensure this typical "glue" information is authored. The point is that as you near midpoint of iterations for a release, the big picture starts emerging and you start revising and enhancing topics that you (or another writer) had drafted earlier in the release. Your topics begin to evolve, just as the product features themselves evolve as one story is delivered, then another story is delivered that enhances/changes the feature originally built in the first story. Just as the developers do not need a monolithic design spec to guide their work, the tech writers don't need a monolitic documentation plan to guide their work either. You won't know at the start of a release what shape your final documentation set will take. And that's perfectly okay. In fact, it's better than okay because it reflects the reality of large, complex software development projects. The beauty of Scrum, when it's done right, is that every story you work on is delivering new user value. It's perfectly fine if you end up redoing a feature that you originally built two sprints earlier, because you wouldn't be doing the rework unless somebody convinced the product owner that doing so would add enough additional user value to the release. Likewise for the documentation: if you get to a certain point in the release where it becomes obvious that spending some time to glue together all the topics developed so far will add user value then the user stories to state that fact will write themselves and you won't have too much trouble convincing the product owner to ensure that some teams pull those user stories and create those glue topics. In other words, you don't have to "sneak in" the high-level documentation work or spend overtime getting it done. You should be able to convince the product owner of the value of doing that high-level documentation work in some of the later sprints in the release. And if you can't convince your product owner? Then don't do the high-level documentation work. Let Scrum work for you and let failure (on the documentation level) be the impetus for changing tactics in future releases. Let the product be released with a user guide that is less than optimal in terms of top-down flow, reader access, and glue topics, etc. If it turns out that user documentation with rough edges is truly a problem for your customers (and therefore ultimately your sales people), then customer feedback (or feedback from internal stakeholders) will reflect that fact. Eventually feedback like this will convince the product owners to give due consideration to the "doc hardening" user stories that you suggest in future releases. And who knows? You might be surprised at how many rough edges your users will tolerate. Many of us writers have been trained to strive for perfection in our documentation, but if we're honest, a lot of the effort we put in to finely polish our documentation (and hopefully win STC competitions) might be better spent elsewhere. What if you can crank out a larger amount of useful information by focusing less on aspects of "polish"? Ultimately, what's of more value to your users?

Group decision making with mixed high- and low-context communicators

Think about your typical staff meetings and planning meetings, where there are problems to be solved and the entire group is solicited for ideas about how to solve those problems. What usually happens is that some people need no encouragement to throw out lots of ideas--to the point of seeming to overtake the meeting. Other people stay relatively quiet and might say very little, or even need to be asked "what do you think?" before they say anything at all. This common group decision making dynamic isn't because the more quiet people lack plenty of ideas they could contribute. Instead, it's due to the communication gap between high- and low-context communicators. What's happening is that the low-context communicators feel perfectly comfortable throwing out their ideas and observations at every opportunity, expecting everyone else to jump in with their ideas too. Like the players on a soccer field, every low-context communicator is actively trying to control the ball and collectively move it up the field towards a goal (concensus). If the ball gets taken from you, that's no problem; it's part of the game and part of the fun. By contrast, the high-context communicators prefer to play ball by having a leader throw the ball to one person, who throws it to the next, etc. until everyone's had equal turns and eventually the chain of ball-passing gets the ball to the goal. In other words, high-context communicators don't feel comfortable jumping into the fray and trying to grab the ball for a while; they feel that's too combative. Instead, they are usually waiting to be invited to contribute their ideas. Now that I've been intensively learning about agile planning and estimating techniques, it strikes me that agile planning games, such as planning poker, provide an excellent technique to bridge this divide between high- and low-context communicators, resulting in greater input from the high-context team members (and fewer feelings of "not being heard" or "not being able to get a word in"). Agile planning games can also make your meetings go much faster by removing all extra discussion that isn't really about the decisions you're trying to make but is really about the low-context and high-context communicators attempting to help each other see what they're trying to say. ... Now for the fun part: the preceding paragraph is where I'd end this post if I were a high-context communicator. What I've said so far assumes that you know what high- and low-context communication is, that you know how agile estimating/planning games work, especially planning poker. And most importantly, it assumes that you consider me enough of an expert that I don't need to elaborate or explain my assertions. My post up to "...the fun part" is also typically how high-context communicators contribute their reasoning and observations in a planning meeting of any sort. As you'll see if you continue reading, high-context communicators tend to make a lot of assumptions that can leave low-context communicators fumbling in the dark. The rest of this post is for the low-context communicators, and also for the high-context communicators who might not actually be familiar with the domains of agile development or high/low context communication, or who might not perceive me as an expert who knows what I'm talking about. ^.^ Some readers might be familiar with the concept of high-context cultures and low-context cultures and the challenges of effective communication and collaboration when your teams comprise members from both types of culture. At my previous employer, where offshoring to India was all the rage for a time period, the mandatory classes on working effectively with Indian team members went into great detail about the inherent challenges in collaborating without offending them with a typically American direct communication style, and how it would be difficult to get suggestions for improvement or straight answers about project status on their end for a variety of reasons centering around matters of status and hierarchical relationships. But in the past few years I've been learning that a similar high-context versus low-context divide exists within American culture too. And unfortunately, this divide can hamper group decision making to a significant degree, especially in the format of typical non-structured meetings so common in the American business environment. As I've become aware of this communication dynamic, I've attempted to bridge the divide with varied success (and failure!) over the years, but the collaborative decision-making techniques used in agile development that were demonstrated last week during my company's Scrum training opened my eyes to the fact that with the right techniques, you can effectively work around the inherent challenges of getting high-context and low-context communicators to make decisions together. If you're not familiar with high-context versus low-context communication styles, here is a whirlwind summary:

High-Context Communicators	Low-Context Communicators
Favor context over content. In other words, their actual message is often quite different than the literal words they use and relies on situational and relational circumstances.	Favor content over context. In other words, they expect their words to be interpreted literally without regard to situational or relational circumstances.
Favor non-linear discovery processes and less reliance on logic and rationality	Favor linear discovery processes and strong reliance on logic and rationality.
Expect the listener to already understand everything about the subject being discussed.	Feel it's important to level-set a discussion by recapping facts and other details.
Expect everyone to rely on internalized understandings of what is being communicated, similar to how in-jokes work.	Feel it's important to recap and summarize what has been communicated or decided to ensure that what was transmitted has been received without mis-interpretation.
Strongly prefer face-to-face interactions and feel blind when the conversation takes place in a written medium or over the phone.	Are perfectly comfortable with conversations that take place in a written medium or over the phone, and are surprised when their objective, clearly-stated words seem to have been misinterpreted, or even worse, perceived as offensive in some way.
Feel that getting things done relies strongly on relationships with people and attention to group process.	Feel that getting things done relies on following procedures and staying focused on the goal.
Tend to take disagreement personally and be hypersensitive to non-verbal signals of conflict. Any perceived conflict must be resolved before discussion can continue.	Tend to take disagreement as something objective about the issue being discussed and be oblivious to non-verbal signals of conflict. If conflict is perceived at all, the tendency is to ignore it and get on with the task at hand.
Are more comfortable in hierarchical social/work structures where there is a strong leader and responsibility is concentrated at the top.	Are more comfortable in non-hierarchical social/work structures and tend to feel strongly that everyone is equal and everyone's opinion has equal merit.
Strongly prefer to be invited to speak and don't feel pressure to break a silence or keep the ball rolling. Silence is an opportunity for introspection and reflection. It is considered polite to be silent for a while to show that you are carefully thinking about what has just been said.	Don't need any invitation to speak their mind and feel lots of pressure to break "awkward silences". It is considered polite to fill the silent gaps in conversation and to respond quickly to what has been said to show that you are actively engaged in the conversation.

Some extreme examples of the difference between high-context and low-context communicators:

• In a high-context culture, it would be rude or offensive to ask a person directly "what do you want?" They would expect you to have already thought it through and to have done your homework about that person and their desires before engaging in communication about the subject. Conversely, high-context communicators assume that because you should already know everything about the subject being discussed, they don't need to recap any details or work out any decisions with you. For example, in high-context cultures, meetings are essentially an official "ceremony" where the already commonly-agreed decisions are announced. The decisions were already arrived at through numerous back-channels before the meeting.
• A high-context listener can get the involuntary impression that the low-context speaker thinks they are stupid because the low-context speaker starts explaining everything. Conversely, because high-context speakers don't explain everything, low-context listeners can feel like the the speaker is jumping to conclusions or making non sequitur statements.
• A teacher is late to class regularly in a high context culture. The director of the school asks a teacher's friend about the teacher's health and happiness, and indicates that the teacher's late arrival for class might have been a sign that something was wrong. When the friend conveys the director's concern to the teacher, the teacher knows exactly what the director meant and is never late for class again.
• A low-context business executive might say "let's make a deal", and the high-context manager might reply "Is your son interested in learning about your widget business?"

So these are commonly understood differences between high-context and low-context cultures, but let's look deeper at how these same important differences exist within a given culture. Especially in America, which is a melting pot of cultures. I can make the following sweeping generalizations about American culture that I feel are accurate. If any of these seem inaccurate to you or you cannot personally identify with these, remember that there's plenty of wiggle room for individuals to be different from the norm described by a generalization:

• The male gender tends to have more low-context communicators
• The female gender tends to have more high-context communicators
• Engineering and musician types tend to have more low-context communicators
• Sales, marketing, product management, and executive functional management types tend to have more high-context communicators
• People raised in secular or non-hierarchical subcultures tend to have more low-context communicators
• People raised in fundamentalist or hierarchical subcultures tend to have more high-context communicators

For example, I'm a male engineering type raised in a secular subculture and I'm extremely low-context. My wife jokes that I border on the verge of Asperger Syndrome when I'm in focus mode on any task, and she has lived closely in the past with a person who had clinical Asperger Syndrome. When I'm not in focus mode, I can spare more mental bandwidth to what I call "my social circuitry" and be more aware of receiving and giving non-verbal cues. My wife, by contrast, was raised in a fundamentalist and hierarchical subculture and she's extremely high-context. In her upbringing, it was a critical survival skill to intuit exactly what a person was really saying, because the actual words could not be trusted at all. When we have misunderstandings, the root cause is very often because we sit on opposite ends of the spectrum between high-context and low-context communication styles. In these situations, I'm not giving her enough contextual cues and wonder why she doesn't take me at my word, while she's expecting me to intuit all her contextual cues and wonders why I'm taking her words literally and not seeing what she's really saying. Does this sound familiar? Have you ever run into this type of communication gap in your close relationships? The problem is that this communication gap happens in the workplace too, but it can be harder to see it because we all work under a veneer of professionalism and try to stay focused on business goals and status reporting in most of our workplace communication. Agile planning techniques like planning poker are great at leveling the field between the high-context and low-context communicators. When you bring a group together to estimate how long a complex task might take, or what the best course of action might be, what typically happens in unstructured meetings is that the person who knows the most about the subject (or thinks they do) blurts out an estimate or idea, and that action instantly colors what everyone else might have been planning to say. Especially if the first person to jump into the fray is considered a thought leader by the group. In a technique like planning poker, however, nobody is allowed to go first, and everybody is invited to give their opinion. When the entire group has finally placed their cards face down on the table, all cards are revealed at the same time. The two people who gave the highest and lowest estimates are invited to briefly help the group understand their reasoning. Total discussion is usually limited to two minutes, after which the discussion is stopped and everyone does another round of face-down estimates, which are revealed at the same time again. This process continues until the estimates converge on a number that nobody strongly objects to. Usually, this takes no more than three rounds and two 2-minute discussion periods. Why this works to arrive at group concensus so quickly is rooted partly in the fact that the low-context communicators are reined-in: they're not allowed to blurt out (rush in and take control of the ball), and the only people invited to talk the most are the two people with the outlying highest and lowest values. Finally, discussion is limited to two minutes per round, so there's more pressure to keep your comments short and not elaborate with endless detail as low-context communicators are prone to do. As for the high-context communicators, this process invites them to give their input with each round of laying down the cards, and invites them to speak if they were one of the low or high values. Thee are other variations on this method of planning poker, such as the one taught to my company by our agile trainer, but it shares these same tactics for reining in the low-context communicators and giving permission to the high-context communicators. Even if your company doesn't use agile, you might want to look into planning poker or books on agile estimating and planning. Many of these techniques can be adapted, with a little creativity, to any type of group decison making endeavor.

Challenges of real-time collaboration among distributed team members

How does a distributed team perform the basic Scrum techniques of all day real-time collaboration, planning poker, and task boards? I ran into a great example this week that demonstrated why the consultant advising my currently company during our transition from waterfall to scrum warned us that it's much easier to implement Scrum and to quickly achieve good velocity by having 100% collocated teams. We're fresh out of formal training and looking at starting our first formal sprint just two weeks later on May 4. The training week was a whirlwind affair of teaching us the basic techniques (which work fabulously when you're all together in the same room. However, there was no time to really think about how we were going to do this effectively once two of us went back to their remote offices in other states. So Monday rolls around and an email thread gets rolling regarding some ideas for how to resolve some of these basic communication issues before our first day of sprint planning on May 4. By 10:59am, two questions had been posed for the entire team to weigh in on. 2 hours later, just over half the team had weighed in on one question, and only 2 people had weighed in the other question. Long story short, follow up emails and IM pings were needed to finally get all members to weigh in by more than 5 hours later. If we had posed those same questions during an ad hoc discussion when we were all in the same physical bullpen during training week, a 5-minute discussion or less would have achieved consensus on both questions. As this example shows, email and other forms of non-realtime collaboration such as discussion forums are anything but agile, and seem like the wrong tools to enable Scrum among a distributed team. So the first basic technique of Scrum--all day real-time collaboration, which I like to call "the virtual bullpen"--requires some special tools to enable. Doing this through phone systems and all day conference calls is cumbersome and eats up valuable ports that are expensive to maintain. A capable tool that might surprise some readers is Ventrilo, which if you know about it at all you probably associate it with online gaming guilds and not serious business endeavors. Ventrilo is very inexpensive and can scale cleanly up to 200 concurrent voice users. It stays on all day in a simple client window like a typical IM client. When you want to talk to the group, you just push a button while talking. No need for cumbersome headsets: it works just fine with a desktop or laptop mic and cheap speakers. But even if you find a capable all-day voice collaboration tool like Ventrilo, that doesn't help your teams that are spread across timezones and can only communicate via voice during a short window each day. Voice collaboration is useful only to the people who are available when the conversation is happening, after which it is lost and you're reliant on your teammates filling you in later with summary information, which defeats one of the main techniques of Scrum--close collaboration all day long. The most promising tool we've found so far that avoids the downsides of a real-time voice system seems to be text-based realtime collaboration tool called Campfire, which makes it easy to catch up on the discussion that happened while you weren't with the team, and which keeps an easy to use historical archive of every day's conversation for later reference if need be. Of course, if you're not actively keeping tabs on the Campfire conversation stream, we're back to the same time-efficiency problems of email or forums. And more importantly, using a tool like Campfire requires self-discipline to have *all* of your conversations in Campfire and not in your own physical bullpen with the few team members at hand, which can be very tempting. More about task boards and planning poker coming in the next few days.