register | login
  search
Contact Us    News    Blog    Events    Careers    Customers    Employees
You are Here:  ResourcesBlog
Click Here to Get You Copy Today! MindTouch Most Influential Techcomm
 
Follow us on Twitter    Join us on Facebook    Follow us on YouTube    Link to us on LinkedIn

Blog
19

Documentation projects in a collaborative world: Reviewing content

If you ask most playwrights what they think about reviewers, you'd best duck and cover. Ask most technical writers the same thing, and you'll get the same reaction.

For better or worse, many technical writers think of reviews as a necessary evil. Even if you can get the reviewers' attention, which isn't always easy, extracting comments that are relevant and useful can be extremely hard.

How does the review process change when the project team adopts the Agile methodology, or when user-generated content is involved? For the most part, it becomes easier and more effective.

On an Agile project, scheduling the reviews might at first glance seem to be harder. An iteration or a sprint is a tightly scheduled set of activities, and the review has to fit precisely into the schedule.

Fortunately, though, each review involves only a small set of topics. Additionally, there are only a few reviewers -- usually just the members of the scrum team. So, instead of dropping a large documentation set onto a large group of reviewers and waiting a long time for feedback, the review is focused and quick. Because the reviewers' minds are focused on the same small set of product features that are covered in the review, their comments are useful and on point.

The same goes for user-generated content because the scope of the review is so small. It might be harder to identify the right SME or SMEs, but the reviews can be done quickly and can be scheduled at the SMEs' convenience.

So it's all good, right? Well, yes, for the most part it is. However, the project manager still needs to consider a few other things:

  • On an Agile project, make sure that the scrum master understands the importance of documentation reviews and makes time for them.
  • With smaller, more targeted reviews, it's easy to lose sight of the big picture. So it might pay to enlist one or two trusted SMEs to step back and take a look at how the whole documentation package holds together.
  • It's also easy to overlook legacy documentation. Make sure that doesn't happen.
  • Because there are more reviews, and because they have to be scheduled to fit precisely into the sprints, you have to keep careful track of them. When will each review occur? Who are the reviewers? How long do the reviewers have to comment? Most important, do they know what the schedule is and what's expected of them?

What other best practices can you share?

About the Author

Larry Kunz

Larry Kunz is a project manager and information architect with SDI with more than 30 years’ experience as a writer, manager, and planner. He has experienced the transition from book-based documentation to today's integrated delivery of information both as a writer and a manager. Larry is a Fellow in the Society for Technical Communication (STC) and in 2010 received the STC President’s Award for leading the Society's strategic planning effort.


Posted in: Global Solutions
Recent Related Articles:

Review: The Insider's Guide to Technical Writing - If you're a new or aspiring technical writer, you deserve a reward. And I know just the thing: The Insider's Guide to Technical Writing by Krista Van ...

Down to the river: Structured authoring immersion - Mollye Barrett must've spent time in the South. During her STC Summit presentation on the content lifecycle, the Milwaukee-based content-management ex...

STC Summit 2013: Content in a mobile world - On more than one occasion I've gotten up from a conference session or a webinar and thought, "That was really good information. I remember first heari...

STC Summit 2013: Early impressions - Many others are tweeting and blogging about the STC Summit, now in its second day. Here are a few of my impressions. ►I'm thrilled to see so many fir...

Why we love David Pogue - A "mutual lovefest" is how New York Times technology columnist David Pogue described his first STC Summit keynote speech, in 2009. His encore performa...

« Back | |
Comments:
Alyssa Fox
Thursday, May 20, 2010 12:22 PM
Hey Larry, good points. For our doc reviews here, we add tasks for the reviewers to review the doc in the same user story where we doc the piece. User stories cannot be completed until doc is written AND reviewed. It works well because people know when it will occur, who's responsible for reviewing, and that the user story won't be done until the review is done.
Monday, May 24, 2010 11:41 AM
Great points, Larry. I think that, for the most part, because you are working on a small set of topics, reviews should probably not last longer than 2 days. Another thing to make sure of before starting an Agile project is that it's clear to all involved that incomplete documentation at the end of a sprint becomes part of the technical debt. If the documentation task is blocked for any reason, it's imperative that the issue is raised during scrum meetings.

I think the most difficult part of Agile is making sure all participants have a clear view of expectations.
Larry Kunz
Monday, May 24, 2010 11:55 AM
Thanks, Alyssa and Julio. You're both saying that the expectation needs to be made clear that doc reviews are part of the sprint. I absolutely agree.

Julio, you said "the most difficult part of Agile is making sure all participants have a clear view of expectations." The same can also be said of non-Agile projects. I think that Agile, by taking a targeted approach and by insisting on frequent meetings of the team, actually makes it more likely that everyone will know what's expected.
Post Comment

Name (required)

Email (required)

CAPTCHA image
Enter the code shown above:

    

Home  |  About Us  |  Services  |  Solutions  |  Resources
ISO9001 Certification NC & Budapest | privacy statement | terms of use | site map Copyright by Systems Documentation, Inc. | Follow us on Twitter Join us on Facebook Follow us on YouTube Link to us on LinkedIn