I'd Rather Be Writing » collaboration

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.

Blog Sponsors

Design Reviews and Posting Without Answers

Tom Johnson — Mon, 09 Nov 2009 01:07:22 +0000

Recently our technical writing team at work (Information Strategies and Design) started holding regular design reviews. The review sessions are patterned after meetings that our interaction designers hold regularly, in which they get together and critique each others designs and approaches toward user interfaces.

In our design review sessions, a couple of members from our eight-person team share what they’re working on and ask questions about challenges they’re facing. We provide feedback and critique their project.

These design review sessions are one of the coolest things we’ve done as a team. We don’t have a strict team style guide or set of standard deliverables. (We do follow the Microsoft Style Guide and, at times, a thin organizational style guide.) But as far as branding the help material, there can be a lot of variation among the online help files, quick reference guides, landing pages, context-sensitive help, interface text, e-learning, video tutorials, or other help materials we create.

If you’ve ever participated in a creative writing group, the design review works similarly. Team members use common sense and experience to guide their questions and reviews. Somewhat in contrast to a creative writing group, though, you don’t have to bring a finished piece to share.

For example, the other week I was coordinating who would share materials for our design review, and one of our team members told me he wasn’t ready to show it. What? I said. The design review is not about showing finished material. It’s better, in fact, to show what you’re currently working on, while it’s still early in the process, before you’ve cemented everything. Oh, he said. In that case, yes.

Parallels with Blogging

I find that the same mindset works with blogging as well. Often times we think we can’t publish a post until we’ve finished a cool thought, or until we’ve finalized a solution to something. But this past week, I added a couple of posts in which I wasn’t quite sure what I thought. In my Theme Parks and External and Internal Input post, I was only part way into a thought. Commenters added to the discussion and helped me better see insights and perspectives on the issue.

I also wrote a post on working with wikis, A Few Surprises in Using a Wiki for Documentation. I’m not an expert on wikis, especially Mediawiki, and there are many things about wiki authoring that I need to learn. But this didn’t stop me from posting about it. Instead, I shared some of the challenges and issues I was facing. And some of the commenters added information that proved incredibly helpful. For example, see this informative comment by Amalia.

Had I waited until I finished in putting together an entire strategy and methodology for authoring on Mediawiki before posting about it, I would have missed out on the guidance and direction early on. It’s from the helpful information early in the process, particularly with challenges I’m facing, that comments on a blog become the most useful. A blog is, remember, a journal, so it contains thoughts and ideas and experiments in progress — not always finished solutions, completed ideas, or tried-and-true methodologies.

What’s true in design review is just as true in blogging. Sharing the current challenges you’re facing will make your experience in the blogosphere or design review process more helpful and rewarding.

Blog Sponsors

A Few Surprises in Using a Wiki for Documentation

Tom Johnson — Thu, 29 Oct 2009 14:40:15 +0000

Recently I’ve been working on a simple calendar project that uses a wiki for documentation. Although I’ve heard a lot about using wikis for documentation, and have even used them in the past, I ran into a few surprises this time.

1. Authoring directly on a wiki screws up the history of updates.

The way wikis work, every time someone makes an edit, it’s recorded in a history for the page. When I write, I make a lot of little updates here and there, not just within one section, but across multiple sections. I can make 10 updates, apparently, in one minute (or so someone told me, who complained that I was mucking up the revision history). I like to hit Save Page often, especially if I have the whole page in edit mode (Microsoft has taught me well). When I save frequently, the version history becomes somewhat useless, as it just shows my name a million times.

Version history isn't so useful when you use the wiki as an authoring tool

Perhaps the solution is to author on a practice wiki and then transfer finished blocks of text to the production wiki when you’re ready to collaborate with others on the content?

2. The text width is longer than St. Pete beach.

I realize this is probably a setting I could control through a wiki stylesheet, but the default width of text for Mediawiki pages spans about seven or eight miles. This makes it difficult to read.

Wiki column widths are often really wide

Wikipedia has the same problem with length. The optimal width for a column of text is about 75 characters in length (less, actually).

(Here’s St. Pete beach, by the way. Next week I’m going on vacation to Florida and am definitely strolling down this long beach, which is my favorite. I’ll be thinking of Mediawiki while I walk.)

St. Pete Beach -- photo by Hanny Heim

3. Community members seem more likely to make little edits rather than create entire pages.

Last week I was at WebWorks in Texas, and I asked Anne Gentle why no one has developed a plugin to convert from wikis to a help authoring format. It makes sense that people would collaborate on a wiki, finalize the content, and then export to a more flexible format, right? Anne felt there wasn’t a business case for creating such a plugin. What?

But after working with a wiki on this project, I see what she’s saying. In my situation, members of the community aren’t going to contribute tons of content. I did receive some help from another volunteer in the beginning, and he wrote several small sections. But when I took over the page with major edits, revisions, and other additions, it kind of pushed him away.

Collaborative authoring isn’t so engaging if two people are hacking away at the same page, changing what each other writes. Authoring this way detracts from one’s sense of authorial ownership. Instead, I believe it’s more common for a single author to create the bulk of a page, and then have the community add edits, a few sentences here and there, tips and notes. The baker creates the cake; others add icing. By and large, there’s one baker per page (at least that was the case with my project).

4. Navigation is cumbersome.

Mediawiki organizes the content of each page into table of contents automatically. The table of contents can get somewhat long and cumbersome (even as simple as the content is), if you aren’t paying attention.

Writing in a wiki format forces you to think carefully about the organization of your content. If the page gets too long, you can break it up into multiple pages.

You have to think carefully about the navigation

The best-practice paradigm of topic-based authoring — authoring content in small chunks that you can manipulate and single source — doesn’t seem to apply to wikis. If you chunk each section as its own page, readers will bounce from page to page to page. It will become a dizzying experience of clicking and clicking.

Perhaps there’s a way to pull in sections from other pages, but I don’t know how to do that yet. Maybe wikis break down when it comes to single sourcing for multiple roles or audiences. Not sure here.

5. Making updates is incredibly simple.

If there’s a major strength to wikis, it’s the ease of making updates. For example, in looking over my local unit calendar help wiki as I wrote this post, I noticed a couple of inaccuracies. I nonchalantly clicked Edit next to those sections and made updates. I absolutely love the ease of updating a wiki.

For people who need to review the content, it’s easy for them to make changes, add comments, and proceed section by section. Don’t underestimate how important this aspect is in the authoring process. I’ve written before about the importance of living documentation – documentation that you update regularly based on user feedback, problems, stories, and other questions. Because a wiki is a live format, you can tap into it at any time and make changes.

On this topic, also see John Hewitt’s excellent post on living documentation and Stewart Mader’s post, Wiki: A More Productive Medium for Living Documents.

6. Wikis are a web format.

Although I wasn’t too enamored with wikis when I started this project, I’ve come to like them more and more. One aspect of wikis that draws me in is the web format. I’ve realized lately that I enjoy web design. A lot. I like working on the web. I like stylesheets and links and jquery effects and layout, navigation — everything.

I realize that authoring in a tool like Flare produces HTML output, which is a web format, but I dislike the static nature of authoring in a help authoring tool and then uploading the content to a file directory to appear in a browser. There’s a disconnect. It doesn’t feel like web authoring, even if it’s published on the web. It’s more like static HTML authoring.

Although I didn’t fallen in love with wikis in the past, the integration with the web may be enough to convert me. Part of my problem with wikis previously was my expectation that users would contribute more. When that expectation wasn’t fulfilled, I wondered why I was using a wiki.

Now I feel differently. For one thing, wikis ensure a separation of help content from application code. This means I can have access to the help even after applications are released. This is something I feel strongly about. Help content should not be packaged with the application code. When help is packaged with application code, these are the results:

little or no interaction with the user community.
uncorrectable errors that can’t be fixed.
a mindset of it’s-released-so-now-I’m-done.
no time for translation or video tutorials (because the app isn’t frozen until the week before release).

7. Wikis provide a new language to learn.

Wikis are supposed to be easy to author in, and for the most part, they are. However, they also provide a new syntax and language to learn. That can actually make authoring more fun. For example, look at this little player button in the image below.

Making an image link to a webpage

By default, in Mediawiki, images link to themselves (or to a larger picture of the image). In this case, I needed the player button to link to the video tutorial, not an image of the player button on the file:image page. You would think that making an image link to another page would be easy in wiki syntax, right? Actually, it took me 10 min. to figure this out. Here’s the syntax:

[[File:Videoplayer.jpg|link=http://lds.netdimensions.com/ldslive/nd/fresco/repository/html/luc/subscribetoacalendar.html]]

In retrospect, it seems pretty simple. But the link= part I had to dig up.

Concluding thoughts

Strangely, I started this post somewhat antagonistic against wikis, and as I’ve reflected on them, I’m now considering using wikis exclusively. I don’t know what happened, but I like the direction wikis take me. It’s the direction of the web.

By the way, if you have any feedback on how to improve my calendar help wiki, please let me know.