Cranking widgets: “Getting Things Done” (GTD) as a tech writer

“Getting Things Done”, David Allen’s productivity method, works well for a technical writer who’s lined up tasks, so they’re ready to go and as easy as cranking widgets. Here’s how in my #2 GTD Principle for Tech Writers. (My #1 principle is about universal capture.)

Cranking widgets

Most of us technical writers face two different types of tasks: Deciding what to do – and actually doing it. It’s the second part that David Allen calls “cranking widgets”. It sounds like a mindless activity, but I take it to mean to get down to our craft and actually write. (For a more GTD-like take, try zenhabits’ recipe…)

I believe, and have experienced, that it makes sense to distinguish and to separate those two types of tasks as soon as a task appears. That gives me a slim chance that I’ll even have the time to decide before I actually have to do it.

The benefit is that I get to group similar tasks together and do related work at once, so I don’t have to jump around in the documentation with every single task I get.

The challenge is to juggle the deciding and the doing. Often I don’t have the time to do all the deciding until my inbox is empty and all tasks are neatly laid out and ready to be done.

Deciding before doing

This kind of task often comes disguised as the second type:

• I get a phone call that asks me to correct something in existing documentation.
• I receive an email about something that hasn’t been documented yet.
• I get a request to furnish screenshots for a localized manual.

All these things need to be done eventually. But for efficient and effective documentation, it makes sense to first decide what to do exactly:

• Is the correction in existing documentation actually legitimate? And if so, when is the best time to do it?
• Is the missing documentation actually missing, or overdue from the latest release, or really part of a future release? Again, when is the best time to write and provide it?
• What’s the most efficient way to get the screenshots for localization? Do I have to do those, or can I ask an intern to do them? If I should do them, should I change my process and create them along with the ones in the source language?

How to decide

The reason to keep the deciding apart from the doing is that the first engages me in a very different way. Deciding what to do is mainly thinking, planning and organizing: Is a request legitimate and timely? What do I need to do that? When is the best time to do it? This part is mainly concerned with logistics.

My answer is usually one of those four decisions:

1. Do it now. This is what I choose for tasks that simply cannot wait and for tasks which don’t take very long. In other words, tasks which get much bigger by looking and deciding a couple of times. The risk is that these tasks take up much of my daily time, but the reward is that they’re in and out fairly quickly.
2. Defer it to a set deadline. This goes for all requests that come with a deadline, whether it’s explicit or implied, for example, because it’s connected to an upcoming version or release of the documentation. These tasks go onto my to-do-list. You can also put them into your calendar or project plan…
3. Defer it to sometime later. This is for everything that’s currently out of scope or merely nice to have. It goes on to a wish list.
4. Delegate it. This is frequently wishful thinking, because most of the time I don’t have anyone to delegate to… 🙂 But occasionally, I get lucky and can ask an intern to take those screenshots… After I delegate the task, I’ll have to make sure to follow up, especially when it’s got a deadline.

Doing after deciding

Once I have sorted out (hopefully most of) my tasks, I can set about doing them, starting with the most urgent ones, but taking all the related ones together. I’m cranking widgets and, if I’m lucky, I might get into the flow.

Your turn

Does arranging your tasks work for you? Or do you have your work arranged for you? Or do you simply not have the time to even bother? Feel free to leave a comment.

Advertisement

Capture everything, or: Are you “Getting Things Done”?

Of course you are getting things done – like most of us tech writers… But do you apply the David Allen’s GTD method from his book Getting Things Done: The Art of Stress-Free Productivity (GTD)? (Hence the quotes into the title…)

Over the years, I’ve found a few principles from Allen’s method especially valuable for tech writers, whether you are a manager or not. They can also be found in other productivity contexts. I’m describing them as parts of GTD, because it’s a well-known method that explains its principles well – even if the implementation can be cumbersome. But that’s what Zen to Done is for… 🙂

Today, I discuss my #1 GTD Principle for Tech Writers:

Universal capture

The idea of universal capture (aka ubiquitous capture), as I understand it, is this: You’re most productive when you concentrate on the task at hand. You don’t waste “brain cycles” remembering other task. To free your mind from all this remembering, you dump everything into a consistent, trusted system – your universal capture. I find this blatantly obvious – and difficult to do well and reliably.

The problem

As I update documentation, new features need to be described in release notes, one or several manuals and the online help. At the same time, the occasional gap or error needs to be fixed in manuals and/or online help. Due to time and system constraints, I cannot address each issue in all formats as soon as it pops up.

So I need a way to capture any and all issues reliably, so I can forget about them until it’s time to address them. At first, I tried to use my inbox by sorting issues into one sub-folder per format. This approach had several problems:

• Some issues needed to be addressed in more than one format or more than one manual.
• Some issues were thrown up in phone calls or when colleagues stopped by with a manual in their hand.

My solution

I’m now using a personal wiki in our intranet which is, for transparency reasons, open for everyone to see and edit. This page is quick and easy to access and edit. It makes few demands on structure and allows me to be as brief or as elabrate as I can be at the “capturing moment.”

Each deliverable has a section of its own, so I can have the same entry in several sections if necessary. When it’s time to update a deliverable, I know I’ll have all issues captured in my wiki list. As I work on it, I strike through each addressed issue. Around the publication date, I condense all issues into a summary of major updates.

More tips and tricks

Leo Babauta (creator of Zen to Done) shares a few general insights about how ubiquitous capture works and when it doesn’t.

Your turn

Do you use universal capture? Or another method of GTD? Do you find it useful? What tools do you use? Please feel free to comment!

Welcome to summer reruns, part 1

My blog and I are taking it a little easier towards the end of the summer.

I’ve had a wonderful time with this blog so far, and I thank each and every one of you for reading, lurking or commenting. I’ve learned a lot from your comments, and I appreciate your support! It’s been a walk on the beach… 🙂

As we’re gearing up for the new season, here are some reruns from the last year or so.

Popular posts from my blog

Trends in technical communication 2010

This is one of my two most popular posts by far. With the help of several readers, we’re commenting on and discussing two trends from a Scriptorium webinar “Technical Commmunication Trends for 2010 and Beyond”. Sarah O’Keefe predicts that it will include content curation. And Ellis Pratt proposes that technical communications will soon also shape an emotional user experience. Incidentally, Ellis will speak on the same topic at TCUK, so go see him, if you have a chance!

Making it as a lone writer

This is the first post in a small series where I share lessons learned and best practices how lone writers can get ahead. Incidentally, I will speak on the same topic at TCUK, so come see me, if you have a chance!

Reading outside the tech writing box

I’ve found that reading helps my writing, even off-topic reading. Technology journalism works especially well for me. I share my favorite magazines and anthologies and link to five articles that you can read online.

Noteworthy posts from elsewhere

Speaking of reading around. If you want to read up on neighboring disciplines, I recommend these three excellent posts:

Complete Beginner’s Guide to Content Strategy

Complete Beginner’s Guide to Information Architecture

Standardized Approaches to Usability

Choosing the Right Tools

Choosing the right tools is obviously important – but also hard, when recommendations emphasize unique selling points that make comparisons difficult.

My fellow German Marc Achtelig has put together three pages with criteria to help you choose the tool that does what you need:

• Choosing a Help Authoring Tool
• Choosing a Screen Capture Tool
• Choosing a Screencasting Tool

The pages are very thorough and well thought out, but they don’t connect directly to products. As such, they’re great to help you make up your mind before you consult the pages of useful tools on his indoition web site. Or you can consult the HAT matrix and plug in all the features you’ve decided you need.

Marc also has a documentation quality check list which covers similar grounds (though shorter than a book can) as Gretchen Hargis, et al. in their book Developing Quality Technical Information.

As a bonus, all the information Marc has collected can be downloaded as a 100-page PDF.

Index this!

An index is an important navigation device in documentation, especially in print. It helps users to quickly find key terms, concepts, functions, and instructions.

In this post, I share my best advice about building an index. And I ask for your help and opinion on a couple of details.

To make your index entries helpful, anticipate user searches. Think of it as a parallel to online search results. When building an index, think primarily of what users might want to look up and find in your documentation.

To create an index, follow these three steps:

1. Create index entries.
2. Build the index.
3. Clean up your index.

1. Create index entries

1. Scroll through your entire document and search for words and phrases that you want to appear in the index. Select only occurrences with substantial descriptions, not just mere mentions.
2. Create an index entry, depending on your help-authoring tool or other software. Edit the entry to avoid all unnecessary words, such as articles (“a” or “the”) and prepositions (“in” or “by”, etc.).

When creating index entries, consider these issues:

• Redundant entries, where you have several entries for the same thing, may seem wasteful and confusing. However, if users are likely to search for the word “equity” in addition to “stocks”, consider using one of the terms to refer the reader to the other entry.
• Cross-references between index entries is a suitable compromise between usability and completeness: Of course, it is an extra step for the reader to move from the entry “Equity: see Stocks” to the “Stocks” entry. On the other hand, it is much more difficult for writers to keep both entries “Equity” and “Stocks” complete and identical over time. Which do you prefer, as a reader and as a writer: Is it okay for readers to move to a second entry? Or should the page numbers be at each entry?
• Nested entries can help you to structure your index and alert the user to hierarchies of concepts and functions. It also cleans up your index by avoiding redundant words. Don’t have more than two levels, however. What’s your experience: Are nested entries helpful or generally confusing to readers?

2. Build the index

At any time after creating your first index entries, create and preview your index, depending on your help-authoring tool or other software.

3. Clean up the index

After you have created all index entries, rebuild and update your index. Then review the existing index for inconsistencies and go back to the index marks in the text to correct the following issues:

• Omit double entries of the same term, but with different spelling or singular and plural.
• Break up index entries that list more than 5 target pages. Refine index entries, for example by creating additional second-level entries for separate tasks, such as “Setting up”, “Calculating”, etc.

Optimal length and scope of an index is the result of a compromise: Make your index as long as necessary to support readers to use your documentation quickly and efficiently. And make your index as short as possible to spare yourself unnecessary work and the reader confusion.

Whether your index is too long or too short is a matter of judgement. Put yourself into the reader’s shoes once more and review your index. You may find that your index is a little too short and missing some terms that users might also look up.

Read more

Good resources for building an index are these two web pages and three books:

• Kurt Ament, Indexing Single-Source Documents.
• Kurt Ament, Single Sourcing: Building Modular Documentation, “Indexes”, pp. 92-97.
• Thomas Barker, Writing Software Documentation, chapter 14: “Designing Indexes”, pp. 436-453.
• Gretchen Hargis, et al., Developing Quality Technical Information, “Provide a complete and consistent index”, pp. 249-253.
• Jan Wright, The Future of Indexing.

Your turn

Please help me out by weighing in with your experiences and opinions to the questions above. Or feel free to tell me if  I forgot anything? How do you create an index for printed documentation? Should online help also have one, or is the search enough? Please leave a comment.

How advertising is the opposite of documentation

You know that documentation and advertising are at odds, if you’ve worked in either for any length of time. Here’s a conspicuous definition of advertising that’s pretty much the opposite of what documentation does:

I want to make the public aware of something they don’t quite yet know that they know – or have them feel that way. Because they’ll move on that, do you understand? They’ll think they thought of it first. It’s about transferring information, but at the same time about a certain lack of specificity.

I found this in chapter 7 of William Gibson’s novel Pattern Recognition. Last I heard, the book hadn’t yet become one of the seminal texts in advertising, so take it with a grain of salt… 🙂

Three more tips for reading outside…

… reading outside the tech writing box, that is… 🙂 After the previous post, three more items crossed my way which I want to recommend:

1. My friend Scott Nesbitt has a similar and interesting post on his personal blog which I’ve discovered only now… Scott recommends books, articles and blogs and says what he gets out of them, so check it out!
2. I’ve since started another book by Alain de Botton which I can recommend wholeheartedly: The Pleasures and Sorrows of Work, a reflective and well-written “hymn to the intelligence, peculiarity, beauty and horror of the modern workplace and, not least, its extraordinary claim to provide us, alongside love, with the principal source of life’s meaning.” It shares Botton#s knack for observation and style with the previously mentioned Art of Travel.
3. And speaking of writing about jobs and occupations, I also liked the colloquial collection of biographical portraits by Po Bronson What Should I Do With My Life?

Reading outside the tech writing box

Can reading around improve your technical writing? Many writers recommend to read a lot, but discriminately: Margaret Atwood, P.D. James and A.L. Kennedy do,  Annie Proulx, Zadie Smith and Sarah Waters do too, when the The Guardian asked them for “Ten rules for writing fiction”. But does this apply to technical writing, too?

It took me a while to figure it out, but I think reading “outside the tech writing box” helps my tech writing. By “outside the box”, I mean reading beyond an immediate purpose, so I’m excluding writings about tech writing, such as books or blogs, specifications and style guides.

Technology journalism

Most effective for me is well-researched, well-written technology journalism:

• It emphasizes stories and the people behind them and reminds me they are more important in my writing than the latest feature bonanza.
• It helps me to focus on personas and my audience and reminds me where other people in the industry are at – or where they may be headed.
• And with some luck, it’s fun to read and well argued and remind me to try and be engaging in my writing where appropriate.

The kind of writing I mean can be found in print and online in Wired, Slate and Salon, in the New York Times and the New Yorker, the Chronicle of Higher Education and the Columbia Journalism Review, in other blogs and magazines and newspapers.

If you like books, the annual anthology The Best of Technology Writing 2007, 2008, 2009 collects about two dozen articles each year that are frequently worth your while – especially since the first two volumes can be read online for free.

Let me give you a few examples which I think stand out above the majority of magazine articles and blog posts:

• Jeff Howe’s “The Rise of Crowdsourcing” (Wired,  June 2006) first explained to me how off-shoring and outsourcing got a new twist with crowdsourcing of stock photography (such as seen in this blog), serious R&D and Amazon’s Mechanical Turk program.
• John Seabrook’s “Game Master” (New Yorker, 6 Nov 2006) tells the story of Will Wright, the creator of video games such as Sims and Spore.
• Emily Nussbaum’s “Say Everything” (New York Magazine, February 2007) showed me how people who are ten years younger than me have a completely different concept of privacy.
• Dana Goodyear’s “I [Heart] Novels” (New Yorker, 22 Dec 2008) introduced me to cell-phone novels originating in Japan.
• Clive Thompson’s “Brave New World of Digital Intimacy” (New York Times Magazine, 5 Sep 2008) provides an in-depth look at Facebook and portrays its founder Mark Zuckerberg.

What else?

If you’re focusing on a specific industry, you can probably also find outstanding journalism there which is worth hunting down. I’m in financial and banking software. So trying to find good articles with an expiration date beyond the next quarter has been especially interesting… A good starting point for me was an anthology by Michael Lewis and McSweeney’s called Panic: The Story of Modern Financial Insanity with pieces written between 1987 and 2008.

Beyond that, I find my reading cannot inform my tech writing much. Recently, I really liked Alain de Botton’s The Art of Travel for its insights what motivates both travel and art and its concise arguments backed up by well-written examples.

I’m also fond of E.M. Forster’s style and handling of plot and character in A Room with a View. These books, as well as many others, engage me and enrich my life – and remind me that there’s a reading life outside of my job… 😉

What do you think? Can reading help to improve your technical writing? What books, stories or articles have you found inspiring or helpful?

Does change management work for doc teams?

We technical writers are frequently very good with tackling new subjects – but not so much with tackling new processes. That sounds paradox, but it’s quite understandable: The reason we’re so good and flexible about what we describe is often that we’ve refined how we describe it. So changing how we write is a challenge, for writers  – and their managers, too, as Scriptorium’s Alan Pringle points out:

Without good management, the implementation of new processes will likely fail. (I’ve seen bad management kill an implementation, and it’s ugly.)

So how can you employ change management to improve and advance the way tech writers work? Alan explains three specific action points that are especially valuable when you’re moving to an XML-based model, but I’m looking for a more comprehensive angle…

Enter John Kotter

So I turn to John Kotter, who wrote a standard book on change management, Leading Change. Here’s a PDF with the gist of Kotter’s ideas in 7 pages. He lists common errors that impede organizational change  and maps them to a sequence of an “Eight-Stage Process of Creating Major Change”. It addresses problems that are probably familiar to writers and managers:

• Establishing a sense of urgency to overcome complacency
• Creating a sufficiently powerful guiding coalition
• Generating short-term wins
• Anchoring changes firmly in the corporate culture

I think these are good general management tools. But do they work for documentation departments? I find that Kotter’s recipe is frequently undermined by the low profile that documentation often has: I can make a good case that documentation is important and often undervalued. But frequently, its quality and scope are not seen as mission-critical for the success of a product or its manufacturer. Then how do you establish a sense of urgency strong enough that “most managers honestly believe that the status quo [in documentation] is unacceptable” (Kotter, p. 48), so a guiding coalition can be created and sustained?

Managing change with writers

So I try Richard Hamilton’s Managing Writers, one of the very few books about, well – you’ve read the title. Hamilton sounds a bit wary of Kotter’s idea to create a sense of urgency. He calls it the “burning platform” (p. 64f.) which will only stir people into changing if the platform is real and the writers are actually on it. Instead, he suggests Pip Coburn’s The Change Function from which he quotes:

Users will change their habits when the pain of their current situation is greater than their perceived pain of adopting a possible situation. (Hamilton, p. 63)

That sounds reasonable and more tangible, more on the level of writers who ultimately do the changing or not. The danger here is to give in to the evil you know, so you can avoid the evil you don’t know. Also, major change in documentation teams will often require migrating legacy contents or rewriting it, and either one adds tremendously to the perceived pain of the solution which impedes change.

Your turn

What are your experiences with change management in documentation? Do Kotter’s top-down ideas work? Can you give Coburn’s idea the right spin, so the perception leans toward change?

Do you know Time?

We know what IT is and we know TIME and we know that everything is really FINE.

… says Dean Moriarty/Neal Cassady in Jack Kerouac’s On the Road (part 3, ch. 5). Now, Neal was known for a lot of things, but tech writing wasn’t one of them. Still, I believe we writers, too, can know time, so I’ll look at different aspects of time and how they affect the success of our documentation.

Time to produce
This one is obvious: There’s the time to write and produce our deliverables until we have to get them out the door, when the deadline approaches or the money runs out.

Time to consume
Whether our documentation is successful also depends on how much time our users need to find, read and apply it. I’ve seen help where I couldn’t find answers and manuals where I couldn’t tell if a poorly structured 20-page chapter would actually be helpful.

This is when users turn to search engines and forums instead of documentation. As Scott Abel points out: “Users don’t care where they get help from – they just want to find the answer to their problem when they encounter it”, and if it’s from another user at 2:30 a.m.

Knowing time
Users don’t only want help “now”, they also need to know time – literally, as I’ve learned from two incidents last week:

I was watching a documentation screencast with excellent contents. But the Flash player had only a general progress bar, with no indication of remaining time and poor navigation within the playing film. I found it so distracting, I would’ve gladly traded in the benefit of seeing the action on the screen for better orientation and pacing on the written page. Knowing time helps to orient users to where they are.

Then I went to a Pecha Kucha night – and the place was packed. It sounds like a strange concept: Would you go and see a dozen or so PowerPoint presentations on topics you didn’t know in advance by artists and designers you probably not know? Loads of people do – because each presentation is 20 slides for 20 seconds each. 6:40 minutes, and it’s over. You spot a bad one in the first 10 seconds? You take a leak, get another beer and are back in time for the next one… The same idea makes the 22-minute meeting so intriguing. Knowing time helps to focus attention.

Writing for time
So I believe our documentation can be more successful when we make it easy on our users to use and apply it quickly. And there’s a lot we can do towards that end:

• Clear topic structure helps users to orient themselves and learn the lay of the land quickly.
  • Separate topics by type, whether it’s concept, task or reference.
  • Keep self-contained topics short and concise.
  • Insert indicative links to related topics.
  • Imply the topic type in the heading:
    • Nouns lead in headings of concepts
    • Imperatives lead in headings of tasks
    • Names of commands, variables, etc. lead in headings of reference topics
• Parallelism (giving sentences of similar purpose a similar structure) improves scannability, comprehension and retention.
  • Start each mandatory step in a procedure with an imperative verb.
  • Start each optional step with “Optionally”, followed by an imperative.
  • Front-load your sentences, so the beginning of a paragraph indicates what the paragraph is about.
• Minimalism trusts users to figure out some stuff on their own (quotes from John M. Carroll’s The Nurnberg Funnel)
  • Address users with realistic task topics
  • “Help users get started fast”
  • “Rely on the user to think and improvise”

But beware…
… and heed Henry David Thoreau, who gives better advice to writers than Neal Cassady:

Not that the story need be long, but it will take a long while to make it short.

Which aspects of time do you watch out for when writing documentation? Feel free to leave a comment.