Search results

Have Notebook Will Travel

by Tom Johnson on Mar 29, 2009
categories: technical-writing

This is a guest post from Collin Turner about staying afloat as a technical writer in an agile environment.

When the sound of my Outlook calendar groaning drifted across my office I knew I had fifteen minutes to prepare for a rapid-fire succession of meetings that would last three hours ... the "Agile Gauntlet." It was a daily occurrence and a price I willingly paid for the opportunity to write documentation in a functional Agile environment. Survival consisted of a few barebone rules:

  1. Adopt a GTD (Getting Things Done) system that's fast, dead easy and only as complex as the tasks it contained. I ended up using Evernote with my camera phone* to get snapshots of Whiteboards, Microsoft OneNote to catch bullets (and drop the pictures into the appropriate meeting) and a Moleskine notebook for those ever important "paper" moments.
  2. Ditch the desktop computer and go for an adequately powered laptop that you're comfortable carrying around. Make sure you've got a good battery and wireless connection.
  3. Use your time and resources to build strong working relationships with developers, engineers, project and product managers. You are not necessarily a member of a specific team ... you are ghost haunting all of the teams. Try to be a friendly ghost and leave the poltergeist tactics for those moments when they're absolutely necessary. In the follow up meetings, ask if you can use a voice recorder. It helps keep concepts fresh and separate.*
  4. Set aside a location where you can write, edit, and revise in relative peace. This can be your home, an empty room, bathroom stall, your car ... wherever. If you don't do this, you will go insane.

The meetings were a frenzied walk around of fifteen minute stand-ups between 12 working development teams. I listened, took notes, asked questions, and scheduled followups if documentation was due for specific teams in the current iteration and more information was required. Those fifteen minute pearls became crucial planning and development points for core documentation. After the meetings I solidified my notes by re-writing the pieces most critical to me in the current iteration. Each team meeting note went into that team's folder and any documentation was updated accordingly. It became a process that moved quickly and kept me organized, important when considering the amount of information 12 different teams can produce in a short amount of time! Since the walkarounds were usually scheduled in the mornings, the rest of my day could be dedicated to followups and writing. Once a week we usually scheduled Iteration Planning Meetings where my documentation was scheduled for each team. This gave me the road map needed to navigate upcoming tasks and plan accordingly. I hope you see the emerging theme here. Organization. Obsessiveness is not required to document Agile teams, but dedicated organization is. If it gets away from you once, it's twice as hard to wrangle back into focus. Work in broad strokes first, chisel away until you've created manageable chunks. You'll be amazed at how easy Agile becomes once you've broken it down to simple tasks and follow the process. When your documents are ready for detailing? That's when you find the "quiet place" and focus on the fit and finish. Add and polish the details but remember that your working in Agile. Your documentation is fluid and will change, often. Make it fit the requirements of the iteration, but don't worry about making it the last word unless the project is over. One piece of parting advice? Communication with the teams is as important as anything else. You'll find many developers and engineers who don't see documentation as a crucial piece of the process. Don't fight them or try to convince them otherwise, the time you spend in battle will just eat your iterations and create resentment. Work with them, ask questions, listen, and let them explain their work. Assume nothing and learn everything. This is the key to integrating yourself as a vital member of their team. They will start coming to you with questions and important facts. You will gain allies and Subject Matter Experts -- priceless commodities in any Agile environment.

About Collin Turner Collin is a technical communicator, sometimes author, editor, and photographer usually found deep within the workings of APIs, writing manuals or managing projects. He lives in northern Utah where you can find him out among the mountains or online at Collin is riding out the recession by documenting the hardware industry.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.