I'd Rather Be Writing » collaboration

Guest Post: Wikis Are the Future of Technical Documentation

Tom Johnson — Tue, 20 Mar 2012 14:56:10 +0000

Mick Davidson

The following is a guest post by Mick Davidson, a technical writer with 20 years of professional writing experience.

Before I get started I’d like to thank Tom for giving me this opportunity to bang on about why I think wikis are the future for technical documentation.

Like many writers, up to a few years ago I was plodding around using backwoods technology, stuck with systems that had once been great but now begged to be retired. From a personal angle, I felt I was stuck with dull tools, tools that were not joined up, couldn’t talk to each other, and excited me not one jot.

Then in through the window came the wiki — and everything changed. Now, three years on and two wikis later, I am 100% convinced they are going to be one of biggest and best documentation tools we have. In short: revolutionary.

There are perhaps four reasons for this:

They are simple to use.
They are very flexible.
They expand as your content grows.
They make life as a technical author an absolute joy.

The latter is particularly important for me as I do not go to work to trudge through thousands of words with something as dull as a word processing package. I don’t want to use a system that hedges me in: I want more. I want a technology that gives me what I need and a lot more besides. And I want excitement!

There is at least one wiki system that offers all this. This system is called Confluence, by Atlassian, an Australian company that has, in less than ten years, come from nowhere to being a major player with 18,000 clients worldwide including Adobe, Twitter and Facebook. This is enterprise with a capital E. But don’t just take my word for it, see for yourself at www.atlassian.com.

There are many other wikis out there, and I’m sure many of them are very good, though I’m not sure they are all enterprise level. Small can be beautiful, but corporations want technology that punches at the same weight as they do — or higher, and because they want to feel safe. MS Office is everywhere because it delivers the goods for many businesses. However, MS Office does not and cannot do what I felt we needed. And nor did any other system I investigated, all of which were far too rigid and expensive.

What we needed was a flexible, extensible system with built-in macros that enabled us to extend what we once called documentation into what is now known as content. Content can be words and graphics, as well as slideshows, audio and video etc.

The system also had to allow us to build and expand the structure as we needed to, easily and without fuss. As a lone author, I don’t want to spend my time building pages and structure — I want to spend it on content that is, for users, as interesting and rewarding to read and experience as it is for me to create.

So, apart from all that, what does working with a wiki offer technical writers? How does it let us do our job better? Why is it more fun?

For a start, the wiki offers simplicity in every direction. In Confluence, and this may not be true of all wikis, it’s ridiculously easy to create a set of pages that are linked to each other and to pages elsewhere. Structures form of their own volition as your content expands. Styles and formatting, which are already set up but can be changed by editing the CSS, are enforced throughout all pages, even when you import a Word document. Sure, you can’t stop people adding their own styles, but you can’t in Word either. And, as technical authors, we obviously don’t need to be told to stick to our in-house styles, so using what’s there isn’t a problem.

Two of the biggest advantages are searching and linking. For me, these two things are possibly the most crucial elements. If there was one thing clients used complained about, it was the limited search capabilities offered by more traditional documentation. Before the wiki we had something like 70 user guides, how-to guides, white papers, and various other documents. If you wanted to find something you had to go through each document, one by one — which is a tedious and often frustrating process, especially if you’re looking for topics that might be in more than one guide. A wiki can be viewed as a database of information that lies behind a very attractive front end — all of which is searchable at the same time.

With a wiki, everything is connected. Run a top level search and you search all your user information — in a second! And if you get too many results, you can simply modify or refine your search to focus it onto content sub-sets, by using labels (or tags as they are also known). In Confluence you can also search by date, the page’s author, and content type. For example, you can search the graphics as well as page names and words. In the end, both you and your clients benefit from this functionality.

And yes, I know you can achieve quite complex searches in other systems, but in my experience, you cannot create them as easily and quickly as you can in a wiki.

Wikis also offer advantages with linking. Links not only provide an alternate way of navigating, they take you to related content, wherever it is, so you can surf pages in the same way you’d surf content in any other website. The fact that you can link to specific topics directly from your software (surrogate help?) is brilliant for lone authors and those with limited budgets and time.

And these are just a couple of the benefits. We haven’t begun to explore collaboration. We’re now getting developers to write user content of their own free will, and clients help us improve documentation by adding comments.

Did I tell you that I’ve just started setting up a user forum in our wiki? Yes, me, the technical author, not a programmer or a web developer. With the wiki this opportunity is in my hands.

Then there’s the ridiculously cheap price. Well, in Atlassian’s case anyway. I doubt that you’ll find anything that offers so excellent value for money as a Confluence wiki. Ok, maybe you will if you’re looking at their other products such as JIRA.

For the last 12 months I’ve been writing all our user information in our Confluence wiki. Before that I used another enterprise-level wiki for two years. Enough time, I think, to get a very good picture of what wikis can do and understand what their potential is. And I strongly believe they are the future. So much so, that nowadays I’m only really interested in working for businesses that use them. Anything less would be, well, less.

But don’t take my word for it. Find a wiki that seems suit your needs, download a trial version and see how you get on. I doubt very much that you’ll regret it.

Mick Davidson has been a professional writer for 20 years as a journalist and technical author. He works mainly in the software industry and attended Atlassian’s recent Unite conference in London, where he took nine pages of notes. He can be contacted via at mjmdavidson@gmail.com. You can follow his blog at http://davidsonmedia.weebly.com/techno-blog.html.

Blog Sponsors

Why don’t technical writers use wikis — or do they?

Tom Johnson — Fri, 24 Feb 2012 07:26:50 +0000

The following is a guest post by Sarah Maddox, a technical writer at Atlassian.

Sarah Maddox

In a recent conversation, Tom mentioned that he’s been pondering this question: “Why, in a time when collaboration is more important than ever, do wikis still remain mostly unused as a help authoring tool in tech comm departments?” Tom asked me to join his ponderings and write a guest post on the topic. Thanks for the invitation and the thought-provoking question, Tom!

I started by thinking about the question itself. Do we know how many people use wikis as a help authoring tool, and what do we mean by help? For this post, let’s say that “help” means technical documentation in general, which I think is the thrust of Tom’s question.

Is it true to say technical writers don’t use wikis?

Serendipitously, two bits of news appeared just as I was about to put my ponderings to paper.

The first was a guest post by David Kowalsky on The Content Wrangler: Collaborative Authoring and Communication Tools Help Writers, Editors, SMEs Work Together. The post discusses a number of collaboration tools, yet wikis get only a very brief mention: “Wikis are becoming more widespread.” That’s it.

So, that post lends strength to the surmise behind Tom’s question. Wikis are only barely in the picture.

Then another bit of news popped up – the results of the 2012 WritersUA Skills and Technologies Survey. When conducting the survey, WritersUA provided a list of popular user assistance technologies and asked the respondents to value the importance of those technologies in their current development efforts. The technologies section of the survey shows that 28% of respondents rate wikis very highly.

28% is not to be sneezed at.

One respondent noted:

Ask again next year and the landscape will have changed dramatically. We intend to migrate from Webhelp to a wiki/kb delivery model and I can’t wait!

WritersUA also provide details of specific tools, where wikis are mentioned quite a bit too. Try searching the page for “wiki” and “confluence” (because the latter is mentioned without the word “wiki”).

Rephrasing the question asked in this post

Based on the WritersUA results, I’ve changed the question slightly. Instead of asking why wikis remain mostly unused as a help authoring tool, let’s ask, “Why don’t more of us use wikis as a help-authoring tool?” It’s an excellent question to address in a blog post. There are likely to be some passionately-held opinions and some great stories around the use of wikis, experimentation with wikis, trials and tribulations as well as thrills and conquests. Bring ‘em on, folks.

So, why don’t more of us use wikis as a help-authoring tool?

I think the crux of it is this: each type of tool makes one set of functionality easy, and supplies other sets of functionality via add-ons or processes that are less comfortable.

Wikis excel at collaboration, notifications and monitoring of updates, integration with other web apps, sharing content, and social features like networks of colleagues and status updates. They also provide instant gratification, by publishing updates as soon as you click save. (That’s the default behaviour, though in some wikis you can configure a workflow to delay publication.) Wikis are great at publishing good-looking documentation with a minimum of fuss and bother.

Wikis are not so good at version control across a documentation suite, single source publishing, or topic-based authoring. They were not originally designed with that focus in mind. But there are add-ons currently available that extend the wiki functionality in the directions we need, and there are more add-ons under development that will do it even better.

Dedicated authoring tools excel at single-source publishing. The newer tools focus on structured authoring. Many of them either have their own version control system or integrate with the same source control tools used to store code. On the other hand, such tools are designed for use by a small, dedicated team. They tend to lock out people who are outside the technical writing team, due to license costs and/or technical complexity. Collaboration is therefore difficult. There is a publishing step between updating the content and making it visible to readers, which may require a delay of some hours until the documentation can be built. Some tools have introduced social features such as commenting, but the published documentation suite does not offer the people-focused experience that a wiki offers.

Can you have all the features in one tool? That would be great, and the need is there. I don’t know of a tool that elegantly satisfies all requirements. Not yet. But there are some promising developments underway. Because I’m so deeply involved in the world of wikis, I know of the excellent plugins and add-ons under development to add workflow, single sourcing and sophisticated version-control to a wiki. I’m sure that people reading this post know of the new collaborative and social features being introduced into other tools.

Weighing up priorities

Technical communication is a broad and diverse field. There are as many ways of categorising what we do as there are environments that we work in. Not surprisingly, there are as many ways of prioritising our needs too. It’s up to us to choose the tool that fits our requirements. Each tech comm team has to weigh up the priorities, based on the aims of our organisation, team and audience.

But here’s the thing: We can help by knowing the capabilities of each tool, and educating our organisations about the benefits of each.

It can be hard to know the capabilities and functionality of a wiki, and especially the capabilities that are useful to technical communicators. Wikis are constantly evolving. Sometimes additional functionality is available via installing a plugin, but it’s difficult to find that information. Or perhaps the features are there in the wiki, but are not packaged and labelled as something useful for technical documentation. For example, wiki documentation may talk about spaces, watches, notifications, RSS feeds. We need someone who is already in the know, to describe the features and show us how to use them in our workflow.

Maybe those of us who use wikis are just not especially vocal about it. Here’s a suggestion: Wiki huggers need to jump up and shout it out: Kiss my wiki.

A lot of it comes down to communication and help.

Difficulty harnessing the power of the crowd

Collaboration is a consummation devoutly to be wished. (OK, maybe not for all documentation suites, but let’s assume that we want collaborative authoring now since that’s the topic of this post.) But it’s not easy. Collaboration can be a messy business. This may be one reason why technical communication teams have not yet implemented a wiki-based solution. They’re looking for success stories. Has anyone successfully opened up the product documentation to updates by external authors? How about letting everyone in the company update the docs, or even company partners and community developers. How about the general public?

This is a broad topic. For my team, I can say that we are making it work, that it’s fun and challenging and rewarding, and that we constantly re-evaluate the way we do things to see if there may be a better way. Our documentation is continuously being updated by subject matter experts (developers, support engineers, marketing engineers, product managers and even a CEO or two). We also have a group of around 50 community authors who update pages every now and then, particularly in the developer-focused documentation.

This post would become very long if I included guidelines on how to manage the updates by everyone. Instead, here are some pointers about the things to consider:

Permissions: The tool you choose must allow you to define groups of people (technical writers, company staff members, community authors, etc) and to assign permissions to each group.
Monitoring and notifications: You must be able to subscribe to an area of the documentation, and receive notifications whenever someone updates a page.
Copyright and intellectual property: You will need to display a suitable copyright license (we use Creative Commons by Attribution) on all the pages, so that contributors and readers alike know their rights. It’s also a good idea to ask contributors to sign an agreement, signifying that they understand the intellectual property arrangements for the content that they contribute. Our agreement is based on the Apache Contributor License Agreement.
Encouraging people to contribute: It’s safe to say that you won’t be deluged with updates. Instead, invite people to update the documentation and keep telling them how much you appreciate their contributions. The experience is rewarding and enlightening. Every day you’ll learn new things about your readers and the way they use your products.
Style guides, templates and structure: It’s a bit of a balancing act. Too much structure can deter contributors. Yet everyone appreciates some guidelines. Templates are very useful, especially in getting rid of that dreaded empty page that needs filling. A light style guide, informative rather than prescriptive, is useful to external as well as internal authors.

The above points are some of the things to consider when allowing other people to update the documentation pages. There’s more to think about when you allow people to add comments to the pages. For example, the volume of contributions in comments can be overwhelming – people are more likely to add comments than to update a page. You’ll need to ensure that management understands the number of people required to handle such input, and the different types of comments that you will receive. In our experience, most comments are calls for help rather than points about the documentation itself. It’s therefore useful if the support team and developers can help respond to the comments too.

The most rewarding thing of all is that people help each other. Someone asks a question, someone else answers, and everyone benefits, without the technical writers needing to intervene at all.

Customisable look and feel

Technical communication teams need to add a brand to the documentation (logos, colours, fonts). They may want a tripane help system or something that looks closer to a website.

In the early days, all wiki documentation looked the same. Bland, black and white with blue links, and if you were lucky a left-hand navigation bar with a table of contents. Above all, there were no rounded corners to be had for love nor money.

Things have moved on, and wikis allow a fair bit of customisation via themes (skins), CSS, replaceable logos, and more. But I think many people still hark back to that era of prosaic look and feel when they hear the word wiki. Here are some wiki sites with a sophisticated look:

splunk>docs
Atlassian developers
PNI
WoWWiki
Any more? If you know of other pretty wiki sites, please add a link in a comment.

What’s in a name?

A couple of times I’ve heard people say that the name “wiki” puts them off. The word sounds trivial, not suited to the powerful tool they’re looking for. It doesn’t reflect the multifunctional tools that wikis have become. Other people say that “wiki” sounds old and dry – very 90s.

Some wikis have changed their description to “collaboration platform” or something similar. MindTouch, for example, is based on DekiWiki. At the moment, the MindTouch website calls its platform the “Social Help Center with Knowledgebase and Help System”. (Note that David Kowalsky does mention MindTouch TCS in his post on The Content Wrangler.) At Atlassian, there are mutterings every now and then about what to call Confluence. Should the word “wiki” appear on the website, we ask ourselves earnestly? The product page title currently says “Content and Social Collaboration Software”.

My 2c? I like the name “wiki”. It’s simple and cute. It retains the history going back to the very first wiki, invented by Ward Cunningham and opened to the world in 1995: WikiWikiWeb, also known as just plain Wiki.

And you know what? “Wiki hugger” sounds so much better than “collaboration platform hugger”!

Honk, beep and wave

So, honk if you’re using a wiki for technical communication. Beep if you’re considering it. Wave if you’re not. I’d love to hear what everyone thinks about the points in this post. And tell me what I’ve missed!

About Sarah

Sarah is a technical writer at Atlassian, makers of Confluence wiki and other software tools. She has 14 years of technical writing experience, the last four of them on a wiki. Sarah’s new book is about developing documentation on a wiki: Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s also about technical communicators. And chocolate. The book covers the points mentioned in this blog post, and a lot more. The book is published by XML Press, and is available on Amazon.com and Barnes & Noble. Sarah’s blog is at http://ffeathers.wordpress.com.

Blog Sponsors

What I Learned About Tech Comm During 2011

Tom Johnson — Wed, 28 Dec 2011 15:31:48 +0000

This past year I learned a few things. As I approach 2012, I’d like to note what 2011 taught me:

Writing documentation in a wiki suits me for the same reasons I enjoy interacting on the web. The web is interactive, alive, dynamic, collaborative, fresh, and unlimited in potential. A wiki, being online, allows me to partake in the same game-like, community-rich environment that I thrive in.
It’s much better to focus on just a few key projects rather than spread myself too thin. I made the mistake of extending my reach into too many projects this year, sometimes taking them upon myself because the applications needed help. As a result, I wasn’t as informed as I usually am about the most important projects, and it showed. Later I pulled back and ignored everything but my two main projects, and I felt much better with this strategy.
I need to set goals to write at work. It’s astonishing how non-writing tasks can eat up the day. Lately I’ve set a goal to write for 4 hours a day at work. I rarely achieve this, though really this goal has caused me to reflect on what writing actually is. If I’m reviewing forum threads to detect issues to write about, or experimenting with a test system to determine steps for documenting a task, isn’t that writing? The typing part comes at the end and is fairly minimal. Regardless, just setting a timer on my iPhone prompts me to dig into the documentation topics and produce something tangible.
Content marketing, played out in the form of corporate blogging, is kind of boring. Corporate blogging isn’t what I thought it would be. Mostly the corporate scenario is stifled by lack of creativity and freedom to explore. You’re expected to toe the line, to avoid controversy, to vet each post through five levels of approval. Comments from readers are usually brief, unenlightening, and often don’t match the topic of the post. I find technical writing more engaging.
A centralized help authoring system is a neat idea, but I hate the lack of control. The idea with a centralized help authoring system is that you install the system on a server with all your styles defined in one central location; an administrator sets up everything to be a push-button publishing solution, and then everyone else just “focuses on content.” However, when you’re used to designing your own help solution, learning to rely on one (often remote) person is discomforting. I like having some control over the design, layout, style, and publication of my help material.
Community collaboration is extremely tough to pull off. I can’t just assign a volunteer writer a topic and let them run with it. I usually have to either gather the information from a subject matter expert or connect the volunteer with a subject matter expert — and then see them through the process with more hand-holding than I want to provide. Still, community volunteers can generate momentum by the sheer number of assignments I have to follow through with. Overall, I have no idea how to engage community volunteers in an effective way, but I think I can eventually figure a strategy out.
Sitting embedded with my project team is more effective than sitting with other technical writers. Sitting with my technical writing team, I end up collaborating a lot on standards, goals, styles, and other issues — which can be useful and important. However, the core substance a technical writer relies on is project-related information. No matter how many IRC meetings, scrums, iteration reviews, and other interactions, nothing replaces the information and rapport you get through proximity to the project team. However, proximity to the project team is just one element. Proximity to end-users is even more important. (See my post on The Proximity Problem for more analysis.)
Just because my job involves sitting at a desk all day with little movement, it doesn’t mean I’m fated to become a couch potato. By counting calories and following a whole-foods, mostly plant/fruit/grain diet, I can actually lose weight while improving my overall health. I’m not becoming a vegan or anything, but I had no idea how poor my eating habits were. The My Fitness Pal iPhone app gave me a wakeup call. The Forks Over Knives documentary on Netflix also made me question the integrity of the traditional food pyramid.
I’m not that interested in fiction. In the fall, I went through a fiction phase that lasted a good three months. During that time, I read and wrote more fiction than I have for the past 10 years. I eventually lost interest and realized I was more attracted to non-fiction for reasons I can’t entirely explain. I like the immersion in ideas (not that fiction is idea-less, but the ideas are shown rather than explained). I enjoy the sense of being “on top of the game” when I’m immersed in non-fiction (such as findability topics) and blogging about these same ideas. It infuses me with a lot of enthusiasm for my job, this blog, and my overall career.
Metadata is the most compelling strategy for findability, but I don’t know how to harness it yet. I experimented with the Semantic Mediawiki extension in a help system, and I liked the ability to tag and query topics in new ways, but I didn’t explore this strategy enough to be successful with it. I feel that I’ve only scratched the surface. There is so much more to discover. David Weinberger’s book Everything Is Miscellaneous, which explores metadata in depth, was the best book I read in 2011.

Based on what I’ve learned, as I go into 2012, I plan to do the following:

Use Mediawiki more.
Set goals to write more at work.
Focus on fewer projects.
Possibly hire an intern to help with the corporate blog.
Leverage community volunteers for non-writing tasks.
Eat smarter.
Read more non-fiction books.
Figure out metadata and findability.

Note: I do change my mind frequently, so no doubt this list will evolve as the months in 2012 pass by.

Blog Sponsors

Why I Returned to Wikis for Help Authoring

Tom Johnson — Tue, 15 Nov 2011 03:39:28 +0000

Last week I was feeling a bit stretched out about not having enough time to accomplish everything I needed to do. Granted, I gave several webinars to a total of 2,000 people, which was somewhat stressful, but I was more stressed about the fact that the help material I’d created could have been much better if I had only more time to focus on it. And it wasn’t just help for one product, but about ten others as well, simply because I didn’t have the time to provide the detail and attention the documentation needs.

It’s not because I’m lazy. I’ve actually become somewhat of a workaholic, working on weekends, sometimes a little in the evenings. The problem is that there simply aren’t enough technical writing resources for the work we do.

This situation was taxing my patience, and I started to think of the immediate solution: hire more people. I already mentioned that we have one opening. This is just back-filling a position from a writer who left. But we need about half a dozen more writers, in my opinion, to do a good job. I thought about trying to hire interns, or trying to recruit full-time volunteers.

While I thought of these staffing solutions, I also thought of other things I have heard our leaders say. We have to find a way to meet the demands of a growing membership without commensurately staffing up, some said. And another: If you set your goals higher than you can achieve, you will change your methods in a way that allows you to achieve them.

While I liked these ideas, I didn’t have a clear idea of how to move toward them. I was constantly working in crisis mode, trying to cross off the top three items from an ever-growing list of tasks each day.

As if the documentation challenges weren’t enough, I had also taken it upon myself to do marketing for technology products across departments. I fished for tech news information in every corner I could find– forums, RSS feeds, intranet content, email lists — and then worked with volunteer writers and subject matter experts to get the articles written. I greased the approval system, learning how to navigate the large number of checkpoints with skill and prowess.

Despite some successes, I realized I couldn’t move in two directions at once, both playing documentation and marketing roles for so many products. I needed a way to scale without simply growing our team with more full-time resources.

A Glimpse of the Solution

Just last week, I felt like I caught a glimpse of the solution. I have a group of 60+ volunteer writers eager to help out. (I wrote about the challenges of managing volunteers last week.) In fact, there are hundreds of church members (as well as non-members) out there who are eager to serve and volunteer for LDS Church writing projects (I work for the LDS Church). I hadn’t leveraged their efforts except for the marketing side of tech, writing articles for the blog about new releases, updates, and other technology topics. I didn’t have them creating documentation because I saw these as separate efforts.

And then it hit me: These aren’t separate efforts. Good documentation about new sites, tools, and resources can be used for marketing efforts. Marketing and documentation don’t need to be separate efforts. I could leverage volunteer enthusiasm for documentation and then pull highlights from the documentation to post as news for the blog.

And what platform would allow 60+ volunteers to contribute writing and editing? The traditional help authoring system we were using didn’t seem adequate. The cost per license and lack of availability outside the firewall made it impractical as a collaborative volunteer platform. About the only platform that works in this situation is a wiki.

One of my colleagues explained that volunteers could write in Word templates and then send me those templates. I could then import the templates into the help authoring system and generate help material from it. This was a system he had used in the past for internal SMEs who wrote content. While this could work, he acknowledged that the process would be somewhat impractical.

One of the problems is that we don’t have a set of number of official products we document. If you look at this list of categories on LDSTech, our users have questions that span across products, departments, and roles. There are dozens of different topics, sites, tools, resources, applications, processes, methods, issues, and other areas that users have technical questions about. Would I create a new project to publish information about each one? The most feasible platform to accommodate such an information ecosystem is a wiki.

Pros and Cons of Wikis

I have to say that, in general, I really like wikis, especially Mediawiki. Wikis have so many advantages that it’s hard for me to understand the case for traditional help authoring systems when you need a collaborative authoring environment. Here are the main advantages I see with wikis in my authoring situation:

Wikis scale infinitely. Mediawiki is actually free, and it supports an infinite number of users. You don’t have to shell out $1,500 per license. People can just log in and start authoring. It scales to support a growing user base.
Wikis remove authoring complexity. Some help authoring tools require a lot of tinkering before they make sense to users. In contrast, adding content to a wiki is fairly straightforward. It’s a matter of asterisks and pound signs and equal signs, for the most part. There is some syntax to learn, but it’s nothing prohibitive. This is essential to expand the base of authors.
Wikis allow collaborative authoring. When you have multiple people working on the same content, nothing is easier than a wiki to facilitate this collaboration. Mediawiki even allows more than one person to work on the same page at once, and is smart enough to handle simultaneous commits of the same sections.

I mentioned that I’ve tried using wikis before. Some of the reasons I abandoned it previously include the following:

Wikis don’t allow you to single source the content.
Wikis are poor at translation.
Wikis don’t get enough edits from users to justify the platform.

I want to address some of these objections, if only to provide notes for myself.

Although many people don’t realize it, content re-use in Mediawiki works much the same way as it does with help authoring tools. If you put content in a template, you can re-use that template in any other page as much as you want (it’s called transclusion with Mediawiki). You can also embed pages inside of other pages.

What you can’t do is easily push the content to a nicely printed manual or do other multi-channel publishing (at least not with Mediawiki). You could, however, come close by embedding pages in a specific order and then customizing the print CSS stylesheet. But in all the feedback I’ve seen on forums and through email, I have yet to come across a request for a printed manual. I do often create one-page quick reference guides that people can print. These seem to satisfy the need for a print experience of documentation.

With translation, while help authoring tools may package up all the essential files and make it easy to export and reimport those files, I don’t think wikis are impractical for translation. Look at Wikipedia, after all. How is it available in so many languages if wikis aren’t suitable for translation? What’s more, wikis allow for community translation in a way that help authoring tools usually do not. Many people from the community can work on translating pages, and they can translate as much or as little content as they want.

Finally, as for the argument that wikis are underused, I think this is because people misunderstand volunteer dynamics. Just adding an Edit button on a page doesn’t mean people are going to edit the content in useful ways. In the same way, if you walk into a room of people and issue a blanket call for volunteers to work on cleaning up the roadside, not many will do it.

Managing volunteers is all about relationships and personal invitations. If you have a group of people who have volunteered to do writing, and you invite them to do specific writing tasks, they do it more often than not. Getting people to participate requires management. It requires some relationship building and follow-up. But it’s possible, and the effects can be somewhat staggering.

I don’t mean to discuss the merits of wikis at length here. Certainly wikis have shortcomings. For example, with Mediawiki, the access model seems a bit narrow-minded to me. You can’t control access at the page level; everything is either open or closed. Skinning themes is also more complicated than it needs to be. But it’s a platform that has many more advantages than disadvantages. And the success of Wikipedia seems to trump all possible arguments against the viability of wikis or Mediawiki as a tool for knowledge.

Conclusion

It’s too early to tell whether moving back to wikis will solve the resource problems I mentioned earlier. But I’m hoping that I will have learned enough about engaging volunteers to make wikis finally work for me.

I know wikis aren’t ideal for every situation. If collaboration isn’t important, if you aren’t stretched thin with resources already, and if your internal technical writing team can adequately handle all the documentation needs, can cover all the various perspectives, issues, scenarios, and other topics that your audience wants to see addressed, then a traditional help authoring tool would be a good fit.

But in my experience, the need for documentation is only growing. The idea that a single writer can adequately provide instruction for a system that thousands of people use — people in different roles, environments, locations, perspectives, and business contexts — is an idea that falls short for me time and again. When I sort through feedback and forum threads, my eyes are open to all the gaps and unanswered questions in my documentation.

Collaboration and interaction are key characteristics of the web for a reason: when you allow others to contribute information, the value of the information grows. It becomes more accurate, more comprehensive, and for those who contribute, the documentation becomes their own. This sense of ownership is perhaps the most powerful effect of a collaborative platform. When your users feel ownership about the documentation, they are more inclined to tend and care for it in the long term. In contrast, internal technical writers often move on to another project after one finishes.

Blog Sponsors

Google Plus as a Professional Communication Tool

Tom Johnson — Mon, 18 Jul 2011 13:43:29 +0000

Shay Shaked

The following is a guest post by Shay Shaked.

I’ve been messing around with Google Plus for about two weeks now. It occurred to me, after reading Tom Johnson’s latest post about content strategy and listening to his podcast about the same topic, that Google Plus is, perhaps unintentionally, the best professional social network with the right usage of content strategy.

I’m not going to explain what Google Plus is in this post. If you want to learn more about it, there are hundreds of articles around the Internet already. I suggest you head to Google’s official introduction to Google Plus, or check out Read Write Web’s excellent coverage on it. What I am going to do here is to contrast Facebook with Google Plus and explain why professionals, especially communication professionals, should give Google Plus a good hard look. Taking into account that the service is still in its infancy, many of the points raised here are still theoretical, especially with most people still unfamiliar or without access to the service.

Google Plus is not just another social network. It approaches the concept from a different direction — one that can make it an excellent learning and communication tool, not just the “no time for breakfast today, but my cat looks happy, lol” kind of shout-out platform. The reason behind this difference is in content strategy, or content management. Google has placed the content control back in the hands of the user. With Google Plus, each one of us gets to wear the content strategist hat and have a go.

Think about it this way: Facebook has had privacy issues for years. We can even say it redefined the term. It’s every professional’s nightmare. People don’t think of what they want to say and to whom: It’s just a jungle out there, so why bother? The two easy options are to either have a professional Facebook persona or simply avoid it altogether. Some of us maintain more than one Facebook account for this reason, while others dig into the depths of the privacy settings and create lists of who can see what. Either way, it’s usually ineffective and challenging to do.

Even if you can manage one of the two systems, the constant changes to the service tend to annoyingly restore the privacy settings back to what Facebook believes should be the default — the “share everything, regret later” philosophy.

As a result, most people do not take Facebook seriously as a professional platform. My Facebook account is full of restrictions meant to block certain people from seeing those photos and posts I don’t want to show up during a job interview. I would probably never use my current Facebook account for professional networking or interests; it’s just not serious and not filtered enough for that purpose. The only thing Facebook is good for professionally is to add contacts in order to spy on them to find out more useful information. This is exactly why you should have as little information on Facebook as possible.

Google Plus is something else. When I want to share an interesting article, I go to “Sparks,” which is a different application altogether, and share an article of interest with people from my professional circle. This specific aspect of Google Plus still requires much work, but the potential is evident in the concept. I created my professional circle (“network”) as soon as I joined Google Plus. Adding people to this circle was natural and quick. Within seconds, I had an article shared with only the people who I know would care about it.

My friends, who are more interested to hear about my latest date, will get the content relevant to them. In other words, I have the responsibility of creating relevant information. I need to choose what information to give and to who, and not just block certain people form reading everything I can come up with. Through the ease of sharing this information, Google Plus does not just invite me to share relevant information, it compels me to create and find information, something Facebook has never done for me.

Yes, Facebook fans can argue that it’s possible to create lists and groups in Facebook just the same. However, the lists are not immediately available and have to be maintained. Facebook’s lists work as filters. Google Plus’s circles work as, well, circles. Just like in the real world.

But there’s more to Google Plus. It also ties in the rest of the services Google already offers in a nice tidy box, waiting for communication professionals to use. All you have to do is to click on the black bar at the top of the screen, and everything is at your fingertips: your documents, diagrams and sketches, conversations and logs, calendar with appointments, and contacts. The potential level of integration here is huge. Think of what happens when you can share not just a link to a Google Doc from within the Google Plus stream, but also have it show up with a short blurb or a summary of what’s in it, perhaps with a thumbnail. Have a wireframe image saved into your online album, and have different people comment and add to it, if needed.

I don’t know if the folks at Google thought of Google Plus as a professional social networking platform, but I see it as a serious competitor of LinkedIn and Twitter, not just Facebook.

Shay Shaked is a professional information visualist with strong background in non-profit organizations. Currently completing his Masters degree in Professional and Technical Communications, Shay has always been passionate about communication and teaching. He is working part time as a teacher and hopes to pursue academia and education in the near future. To view Shay’s blog, visit Technically Writing.

Blog Sponsors

Collaborative Posts Q&A

Tom Johnson — Wed, 04 May 2011 14:06:06 +0000

Kristi Leach interviewed me for a quick Q&A about the occasional collaborative posts that I do on this site. You can read the interview on Kristi’s site, Why Tech Comm. Here’s an excerpt:

When I was deciding on a format for my workshop, Grassroots Documentation Testing, I thought of Tom Johnson’s collaborative posts on his blog, IdRatherBeWriting.com. In collaborative posts, Tom poses a question to his readers (who include many seasoned and successful technical communicators), and they respond with advice in the comments. Read the rest here.

Speaking of collaborative posts, does anyone have a question he or shewould like me to use as the next collaborative post?

Blog Sponsors

The Real Source of Findability

Tom Johnson — Thu, 10 Mar 2011 07:49:19 +0000

I was talking to a colleague today about wikis when he mentioned Google, and how Google has such a brilliantly simple solution that allows users to find content. With Google, there’s a search box. The users type keywords they want information about, and most of the time Google returns brilliantly relevant results.

While some credit is certainly due to Google’s Pagerank algorithm, what enables findability in Google is that there’s so much content on the web to find. If you have billions of web pages, of course the search engine is going to come up with results that match almost any keywords you enter. As a result, because of the mass of content, you have instant findability. Take away the content, leave only the algorithm, and you have nothing.

Above: You find information on Google because it draws upon a wide variety of content authors for the information. Below: A typical help file lacks information because usually only one person creates content for it.

How much of that content is Google generating itself? Almost none of it. The web is like a giant wiki, where anyone can author and publish content. Only instead of adding new wiki pages, we’re all adding our own sites and pages on our sites.

I brought this up as a colleague and I were discussing our organization’s external wiki, tech.lds.org. It’s a wiki that has quietly been growing in size each day, used for myriad purposes both internally and externally. You can do a search on quite a few topics and pull up content — because so many people are authoring. There are probably more than 20 regular authors contributing to that site, with probably 30+ daily edits. When you have so many authors producing content, the result is that someone is going to address a problem that another is searching for. The answers are findable.

The paradigm of a single author controlling all the content for a knowledge domain — keeping it in a tightly structured environment that moves through a strict editorial process — is a model that, no matter how well organized or planned out, will probably fail when it comes to findability precisely because you only have one person creating the content. That one person is inevitably trapped by his or her own experiences, by his or her limited domain and restricted viewpoint, by his or her job role and title. There’s no way a single person can produce the mass of content necessary to enable findability on a wide scale. The person will produce 100 single-focused pages compared to the 10,000 multi-faceted pages produced by an army of authors.

The intelligence of the web isn’t the technical infrastructure or the idea of bandwidth or CSS. Its intelligence comes because so many people contribute content. It’s the true global encyclopedia — Wikipedia is just one part of a larger body of reference information. We’re all contributing to it, page by page.

We’re only about 15 years into this endeavor. Imagine the size of the content repository in 50 years. We’re moving towards a book of knowledge that is growing daily, becoming more and more comprehensive — and it’s because of the individual contributions, not because of a specific authoring tool or process or technology.

It’s a free for all, sure, with any kind of design, format, and style. But despite the variances, people look past design and focus on content. This is why, when we consider enterprise authoring methodologies, what makes the most sense is the authoring methodology that empowers the most people to author.

As more people author, the pool of content grows wider and deeper. Soon you’ll amass enough information that, although it’s a content dumpyard in many cases, when users dig around they find the nuggets of information they’re looking for. It’s not a huge problem if the individual content on each page or project varies in layout, color, and style. The mere fact that the content is there, because you empowered a subject matter expert or user to author it, means that you have content. Content exists. This content gives rise to findability.

Although I have looked at many authoring tools, I think the one that triumps them all is the wiki, precisely because it enables the enterprise to author content. Many times the authoring is stifled and only a fraction of what it could be, but other times large numbers of contributors jump in and author. They produce loads of content. When this happens, the result is something far greater than any single authoring team alone can produce.

In short, findability isn’t enabled by some clever organizational technique such as tagging or faceted browsing or even schema theory. Findability is enabled by empowering all humans to share and publish their knowledge.

Blog Sponsors

Formalizing My Help Strategy

Tom Johnson — Tue, 08 Feb 2011 06:52:42 +0000

In this post I'm putting together a more formal help strategy.

In a previous post, I started to explain my approach to help authoring. I’m trying to flesh this out into a more developed and detailed — but not too long — statement about how I do help. This information would be useful both to project managers as well as other writers I work with. I would appreciate any feedback.

Help Strategies

Because users have different skill levels and learning styles, help material needs to be multimodal in its approach, providing content not only in written format, but also through videos, illustrations, and the interface. With this approach, learning materials for a software application typically include the following:

Videos. Videos are usually brief screencasts that focus on a specific task. As screencasts, the videos are voice-narrated and focus only on the screen, without actors or scenes. The screencasts are short, such as 1-2 minutes, and are created almost entirely by the technical writer. This keeps production costs down while allowing for updates as the application changes. New users, especially visual learners, will typically view a series of videos to become familiar with an application. Videos aren’t meant to address advanced topics or edge cases, but are targeted at new users who prefer to learn by having someone show them how to do tasks.

Quick reference guides. Quick reference guides are usually two to eight page guides containing brief instructions in a visual way. These guides often contain screenshots with callouts and other explanations. The quick reference guides can also include concept diagrams, workflows, and other illustrations to help users understand the application quickly. Text in quick reference guides is brief and compressed, providing more of an overview than specific how-to detail. The basic idea of a quick reference guide is to give the user just enough information to get started in the application. This type of help material appeals to users who prefer some information in a brief, easy-to-digest way as they first jump into an application. Like videos, quick reference guides are targeted to new users.

How-to guides. How-to guides are lengthier printed guides that expand on the application in a more elaborate — but not comprehensive — way. A how-to guide is meant to be read, not merely referenced, and will focus on many concepts and capabilities within the application. These guides are a subset of the total documentation, with topics selected and integrated in such a way as to produce a readable booklet about the software application. These guides are usually single sourced from the online help and crafted in a way to make them pleasing in a print-reading experience. How-to guides are intended for users who want a more in-depth grounding in an application.

Online help. Online help is a browser-based HTML format for help content. Online help is the most comprehensive collection of topics, intended for reference and searching more than anything else. Online help is meant for users who have specific questions or need to search specific how-to’s (often advanced topics) about the application. Online help isn’t intended for people first learning about an application, because the topics aren’t necessarily grouped in a sequential or linear way. Each topic is modular and can be accessed and interpreted independently of other topics.

Interface text. Interface text includes all the language within the interface, from button names, page titles, and error messages to other instructive and navigational text the user interprets to use application. These interface tips and guides are important for users as they explore the interface and learn by doing. Interface text can also take the form of on-screen help text (often shown in hover tips) or as context-sensitive help, which shows a topic relevant to the current page. Interface text accommodates users who prefer to learn by doing.

Help Content

Access to users. Apart from the format, the content of the help material needs to be relevant and useful. In order to produce relevant content in a language and organization that makes sense to users, technical writers need to understand the user’s environment, vocabulary, and tasks. As such, technical writers need access to users. The access could come through phone calls, observations of users, or other interactions. Based on interactions with users, the technical writer may create personas and scenarios to create better help. Personas and scenarios can expand the perspectives from which a technical writer sees an application.

Multiple perspectives. The paradigm of a single author working from a single perspective, usually as an outsider to the actual business context of the application, is a paradigm that typically fails, since no one person can know all the information needed to help users. Contributions from multiple perspectives — from project stakeholders, project team members, community volunteers, and end-users — will help the content reach relevance and usefulness for a larger number of people. The importance of collaboration requires an approach that facilitates multiple authors and distributed ownership.

Editorial roles. Because of the need for distributed authoring, subject matter experts may often be content contributors. In these cases, the technical writer acts as an editor to help style and review the subject matter expert’s content. Other times, end-users themselves may contribute toward the content. User contributions should not be discouraged, nor should it be difficult for users to contribute or provide feedback. Heavy content collaboration may be facilitated through a wiki platform, but not necessarily. Other methods for interacting and content sharing can also be employed, such as with forums or comments below topics. In each case, the technical writer either edits or facilitates the content rather than creating it from scratch.

Perpetual beta. When the application is released, content is not finished. Even though content may be in a semi-complete state, we can never anticipate all the gaps, needs, quirks, and issues that users will encounter pre-release. For this reason, content needs to be published in a perpetual beta state, that is, with the ability to continually update the content even after release. As such, the help content should be stored separate from the application code to avoid release-window-only time frames. Technical writers should be able to update any help content on the fly as needs arise. Because help is usually stored on another server, applications requiring login should employ single-sign-on to reduce a secondary login windows.

Agile feedback loops. Just as the agile process often results in better software development, the same agile process applied to help material can be beneficial as well. To be agile, technical writers need to actively gather feedback about help material to improve it. Feedback from documentation doesn’t always need to be expressed as comments. Technical writers can gather feedback through metrics and other automated processes. Each help topic should contain tracking code to measure hits. Attending live training (or providing live training) and observing users can also be a means of gathering feedback. Technical writers need to be attuned to bug logging systems so they can connect with project team’s tracking of issues, and with the support center so they can monitor incident logs. Communication with product managers is also key to gathering verbal feedback. Where possible, technical writers should automate reports and other feedback on a regular basis and update the help accordingly.

Scope of information. Despite the attempt to provide business relevant content to every user, documentation does not need to provide instructions about everything. Too much information can make it difficult for users to find what they need. An over-abundance of information can dilute core task content and need-to-know topics. However, the technical writer does attempt to provide instructions for at least 80 percent of the typical user’s needs. Efforts to document the remaining 20 percent often fall prey to the law of diminishing returns; that is, for the effort required (tracking down hard-to-find solutions for unlikely scenarios), the payoff is little.

Help Plans and Processes

Prototype language. Technical writers should be involved in projects as soon as prototypes have been created. This early integration is necessary for technical writers to address interface language while there’s still time to make changes. Interface language is a component within the technical writer’s domain of expertise and should be treated as such. Technical writers should work closely with interaction designers in refining prototype language to avoid ambiguity — particularly in global contexts. Projects in which interaction designers are employed at the beginning, and technical writers at the end, often end up with broken interfaces.

Project plans. Technical writers should complete a project plan that provides project managers with a general estimate of the anticipated work and other details for the project. As an industry standard, it takes approximately four hours per application screen to create a help topic. This estimate of time for help topics only, and does not include time for creating videos, quick reference guides, or interface language. The project plan should also address the deliverables, expectations, risks, scope, timeline, and other details for the documentation. Failure to produce a project plan can result in a misalignment of expectations between project managers and writers.

Dual roles. Many times the technical writer becomes a subject matter expert on the application, having explored and examined it at length. The technical writer may become aware of bugs, usability issues, and support requests for an application. However, given the limited technical writing resources available, technical writers should only play these additional roles briefly. Technical writers may log or report bugs, but not necessarily flesh out the exact steps for reproducing bugs in every browser, nor conduct extensive usability testing, nor play support roles on the phone with end-users. If technical writers do play multiple roles on a project team, as is sometimes necessary in agile environments, project managers need to factor in this additional work into the project plan and estimated hours.

Approval processes. Before help materials can be considered complete, they must undergo review by several parties. The project manager should designate someone from the project team to review the accuracy of the help material. (Many times project managers themselves review this material, or assign quality assurance leads.) Other reviews may also be necessary if distributing the content externally. These reviews will add additional weeks into the completion of the help material. The reviews serve several purposes: to ensure consistency of style, to mitigate legal risks with content, and to provide another perspective on the coherence and accuracy of the content.

Tools and Technologies

Tools. Technical writing teams should use the same general set of tools so they can collaborate on files, share tips and how-to knowledge, and be interchangeable on projects. If one writer’s load becomes too heavy, he or she can re-allocate the load to other writers as long as the others can pick up and use the same tools. In most cases, use industry standards rather than open-source tools. Team members should also have the latest versions of each tool to facilitate collaboration.

Collaboration and content re-use. If external collaboration (such as with the community) is important on a project, a wiki works well. In fact, collaborating with large numbers of people in real-time is probably only feasible through a wiki, but the wiki doesn’t need to be the end product (the material can be exported). If only internal collaboration is important, other strategies may make more sense, such as a help authoring tool that stores content in a content management system. Ideally, if all internal collaborators can access and author from a central content management system, and render the outputs in a standard way without resorting to individual formatting, this can help with consistency and reduce the technical burden on content producers.

Corporate constraints. In a large organization, requiring every employee to standardize on the same toolset is difficult. Additionally, many times corporations limit certain tools and technologies from being installed. One must always work within a given environment while at the same time making strides to obtain approvals for more appropriate tools and technologies. Making appeals to industry standards can provide some leverage. Regardless, one can often accomplish the same results using many different tools and technologies.

Constant learning. Because technical writers often handle all aspects of content production, from creation to design to publishing to distribution in a variety of formats, including text, illustrations, video, and e-learning, the technical writer must constantly be engaged in learning tools and technologies. It’s not strategic to wait until the tool knowledge is required and a pressing deadline looms near. Rather the technical writer should schedule regular learning time, perhaps accessing sites like Lynda.com, into his or her daily schedule. When opportunities arise, the technical writer can leverage this knowledge to quickly design, illustrate, record, compile, call, style, or configure help content as needed. This learning is part of the technical writer’s job, and is an element that separates technical writing from many other types of writing.

Blog Sponsors

The Role of the Gatekeeper

Tom Johnson — Wed, 28 Jul 2010 06:04:27 +0000

Sarah O’Keefe’s guest post — The Role of the Gatekeeper is Changing — on Peg Mulligan’s blog is interesting. Sarah writes,

The Internet is removing the traditional gatekeepers for content.

This may seem obvious, but its implications in my life have been profound. I majored in English and then earned an MFA in creative writing. After graduating, I gathered up my best essays and sent them off to literary journals for publication. After months of waiting, I didn’t publish hardly anything. It was frustrating. They were good essays, but they didn’t have the right focus. That timeframe was about 1999 to 2002.

A few years later, I started blogging. First in an experimental, non-committal way. Then I started to gain more focus, and after a while, I realized that I could have as much satisfaction publishing online on my blog as I could in any print journal.

I realize Sarah’s comment was in the context of technical communication, but the principle is the same. Whatever you want to publish, you can. There are almost no restrictions on the Internet. Collaborative platforms empower even the most technically illiterate people.

Sarah writes,

There’s never enough time for in-house professionals to create all of the content that’s needed. Contributions from the user community can provide additional support and build on the official core content.

This statement is more relevant to me now more than ever. I was enthusiastic about a particular project at work, and two weeks into it, the budget dropped. I have to take my half-written help content to the community to help finish it off. And while I have volunteers, I realize that I need a solid collaborative platform with clear directions, easy tasks, and a lot of management and feedback to be successful with community efforts. All my previous efforts to involve community in writing documentation have mostly failed.

Sarah writes,

There is a temptation for business executives, especially in cash-poor start-ups, to dismiss their technical communication staff and simply rely on the community to provide documentation.

This trend always astounds me. Even in my organization, support for professional technical writers varies significantly from department to department. On some projects, the customer (in a specific business department) has a designated writer who handles the material. On other projects, we (the IT department) provide help. But it always frustrates me to see a project manager marginalize help and dismiss the technical writer’s role. In fact, I need to meet with a project manager tomorrow to try to talk sense into him.

Blog Sponsors

Together or Apart: Collaboration Models for Technical Writing

Tom Johnson — Tue, 23 Feb 2010 04:37:42 +0000

Today I spent a rather lonely day writing documentation. I had one team meeting, during which our team gathered for what seemed like a brief second. We then departed back to our respective portfolios, most of us working alone and in solitude toward some distant documentation goal.

Some writing teams sit together. They chum with each other all day long about commas and online help layouts. At my first job as a technical writer, I sat in a long row of cubicles we figuratively called “The Technical Publications Office.” All day long I could listen to my colleagues say things like “Oh my goodness, this guy is writing fused sentences.” Or “Don’t you just love it when all your images disappear from Microsoft Word!” or “Hey Tom, can you help me with something?”

You know what I’m talking about — the camaraderie of being in a group of writers, exchanging comments about projects, bantering about this or that. It’s a cozy, comfortable feeling, being surrounded by other literary kind.

Agile Environments

It’s not like that in my current agile environment, though. In many agile environments, you have to forge your own way, often sitting away from your writer colleagues, embedded among QA, developers, interaction designers, and managers on a project team. Although I’m on a team of eight writers, most of us are spread out in different departments, assigned to different projects. As a result, writing documentation can often be a lonely, long experience alleviated only through Pandora, Twitter, IM, the incoming comments on my blog, and my wife’s scandalous posts.

I know it would be a lot more fun to be desk-to-desk with all the other writers in the organization. We could stop every now and then to feign horror at grammar atrocities or mock the edits our SMEs make. We could easily review each others’ work, provide feedback about parallelism with topic titles, compare TOC layouts, or discuss the style guide.

But I’m more effective sitting next to other employees working on the same project. Sometimes I wear a QA hat and point out bugs (and explain/show them to developers). Other times I coordinate with project managers about customer feedback and concerns. Other times I ask developers to explain how something works or why they built a function a certain way. You need to be close to your project team to interact with them, right? Proximity has an impact on communication, no doubt. But I’m not so sure ours is the best model to follow.

The Book Sprint Model

Last month leaving an STC meeting, as I was walked through an windy parking lot to my car, I caught up with a colleague, Joe, who works as the sole technical writer at a nearby company.

We talked a little about the meeting. And then he said, “Sometimes I have so many questions. I mean, do you ever think we have the whole model wrong?”

“Huh?” I said. “What are you talking about?”

“You have eight writers in your team. Why don’t you all just sit down and tackle a project together and knock out the documentation in a week?”

I’d heard of this model applied to book sprints with open source projects. Anne Gentle has written extensively about book sprints. Tomas at BookSprint Central explains that coming across the idea of the book sprint was the “most important epiphany of [his] professional career.” He explains how few people rarely have the time to sit down and write an entire book themselves. It simply never gets done. He says,

I also knew that there was no way i was going to be able to spend all my evenings for a year writing such a book even if i wanted to. Which i didn’t. And i had a feeling that while i’d collected a network of incredibly smart people, with boundless experience in this field, everyone else felt mostly the same as me when it came to evenings and years. But I also knew that i could convince almost anyone of these incredibly smart people to give away a week of their time to such as good cause. So there were the constraints. Have: One week of time each from a bunch of smart people. Need: Finished book.

His solution was the book sprint. And it worked. He flew in a group of smart, knowledgeable people and sat them down in a room for a week to write. They produced a completed book, which was downloaded thousands of times and translated into numerous languages.

I like the book sprint idea, quite a bit. It reminds me of the Amish barn raising, or a group of guys pulling together to help someone move.

In fact, as far back as 2005 at a conference in Raleigh, I remember Rick Sapir arguing against the one-writer-for-the-entire-project model that’s so common in documentation. Why not have several writers work on various parts of documentation? he said. Everyone takes a little chunk of the application and writes documentation for it. The idea that one writer creates all the documentation for a project is an old model, he explained.

At the time, I disagreed. I said it wouldn’t work because you can’t write effectively about one aspect of an application without understanding the whole. And to understand the whole takes months of exploration and learning. Not to mention the dozens of project meetings. If everyone has to devote the same amount of time learning the application to write about one small part, isn’t that inefficient?

I’m also wasn’t sure how help can be put together in such an independent way. Although each topic in a help system is usually a semi-independent chunk, how do you know that the topics Writer A contributes don’t overlap, contradict, interfere, or otherwise jar with the topics that Writer B contributes?

On the other hand, the group collaboration model has its benefits. Multiple writers working together can see an application from various points of view. The writers are less inclined to become myopic and routine. They can more freely bounce ideas off each other, make more informed decisions about content and layout, and generally approach the application with twice the brain power.

Book Sprints with Community Projects

One day I’d like to try the book sprint model in a corporate setting. However, since major changes within a large organization are hard to implement, it might be more practical to do a book sprint with our community development projects. We have more than a dozen community-driven projects (most of them small) in which the community participates in the requirements, development, and design. This is one of the cool and interesting aspects of working for a nonprofit organization. Some members want to volunteer their time and talents to further the work. We’ve been trying to figure out a way to harness their talents.

Previously, I had been pitching the incentive to contribute tech docs as an opportunity to get experience for your portfolio. But that route wasn’t so effective. Participation was slow and inconsistent.

Next time, I might contact 10 or so community colleagues interested in helping out and invite them to participate in a book sprint. It could be an entire day, one that we dedicate to documenting just one project. An entire Saturday, or something. I doubt I would fly people out to Utah and put them up in a hotel room for a week, because most people can’t take a vacation from their regular jobs for this, but I can see people dedicating a Friday or Saturday or even Sunday to remotely contribute toward a project they believe in, especially if the idea is packaged in the conceit of a “church book sprint.”

Whether you’re integrated into an agile project team and away from other writers, or together with multiple writers on the same project, increasing collaboration is key. Rick was right: the single writer working tirelessly in solitude on a manual that he or she authors from start to finish is dead.