Subscribe to RSSPosts Tagged ‘JoAnn Hackos’
Emerging wiki use - now and future wikis
As you might have seen on The Content Wrangler recently, I wrote a response to JoAnn Hackos’ article, Is there a wiki in your future? and Scott Abel chose the title for my special contribution to his site. I think the title of this blog post - Emerging wiki use - now and future wikis - would have been a better title than “Anne Gentle vs JoAnn Hackos” but unfortunately I learned that his blogging system would cause broken links if he changed the title after I requested a title change. Ah, content management systems, why do they break your heart? 
I do want to make sure that readers know that JoAnn and I are not at odds about wiki use at all - rather, we are both trying to find the best practices for building a wiki that will thrive. My thought on the “vs” in the title is that it is intended to show the polarization on the issues surrounding wikis and technical publications. JoAnn and I have emailed back and forth this week to continue to discuss and find that we are not on opposite sides of the issue.
I’ve happily read the blog entries from other writers that read both articles, with my favorite reference being Sarah O’Keefe’s “eponymous rebuttal” phrase. Subtle and clever, and sent me to m-w.com, so I love it.
A neat outcome so far from this article is that I had a discussion with someone who had experienced something similar to JoAnn’s scenario. One of my readers described a situation where he was creating and updating wiki pages, trying to extract and describe an exact algorithm for an online game. Apparently in gaming communities, the developers can be very tight-lipped about the exact way that game play works (weaponry or armor for example), and the challenge to the gamers is to figure out the best strategies based on their experiences with the game. Without arbitration on the wiki (or customer support forum), though, outright content wars ensue and the wiki content about the algorithm becomes untrustworthy.
It’s a fascinating example. I’d like to find more examples related to technical content to find out what arbitration policies would work well. Let me know your experiences in this area - have you had a need for arbitration on your favorite wiki yet?
DITA round up
Just doing a little data mining of the posts I’ve written about DITA in the last few years. I think that there’s a gap for DITA users who are writers or content creators and not coders. I’d like to say that DITA bloggers can bridge that gap. Join me on the DITA blog by writing your own experiences with DITA.
These posts are ordered from newest to oldest, and I wrote them to share my experiences with DITA and to chronicle some of the Central Texas DITA User Group meetings I attended.
A watched folder for publishing from DITA source files
June 15, 2007: I’ve figured out a way to automate DITA builds where you just drop a zip file of your DITA source files into a “watched folder” and PDF and CHM files are automatically built.
Usability and inline links in user assistance systems
May 19, 2007: Examining DITA’s linking and usability.
Getting Started with DITA
April 12, 2007: A brief overview for a couple of fellow Austin writers who have asked me recently how and where to get started with DITA.
Checking out the new DITA Users website
April 10, 2007: Using a coupon code (it’s BETA) I joined the new DITA Users website for free today.
A new DITA Open ToolKit release and brand new DITA newbie blog
October 04, 2006 : A couple of blog-worthy items in the DITA world
Turning information into DITA topics
September 14, 2006: What would you do to make this particular type of content into topics?
How to substitute your custom CSS when using DITA Open Toolkit transforms
September 07, 2006 : When you want to use the DITA Open Toolkit transforms but you want to use your own CSS, here’s how to substitute your CSS for HTML Help (CHM)
DITA Open ToolKit now has a User Guide
August 22, 2006: Just released last week, the DITA Open ToolKit now has its own User Guide
Using the DITA catalog for your specializations, creating a Public ID
August 16, 2006 : Thought our discovery might help you as you specialize DITA
Evaluating XML editors for DITA
August 01, 2006: Notes from the July 2006 Central Texas DITA User Group meeting
A web-form-based DITA editor
July 14, 2006: Could this be the perfect storm for a DITA wiki?
Troubleshooting tip for the DITA Open Toolkit install
June 23, 2006 : Finally figured out the fix for my DITA Open Toolkit “resource/messages.xml” not found error
Where to put your files and other setup for DITA
June 09, 2006: Working with the environment setup for DITA
Defining OPML and relating to DITA maps
May 31, 2006: I found a nice definition for OPML from whatis.com as their word of the day, and I’m starting to wonder about similarities between OPML and DITA maps
Learning more about DITA
May 18, 2006: Learning about how to get started with DITA and a trivia item for fun
Notes from the central Texas DITA user group meeting
April 21, 2006: Two speakers shared their takeaways from DITA 2006 and CMS 2006
Our DITA experience at BMC Software
March 02, 2006: Link to a case study published about BMC’s DITA experience
DITA from the trenches
February 20, 2006: Information Architect from IBM, Kristin Thomas, presented to the Central Texas DITA User’s Group meeting last week, and here are my notes.
Moving from Books to Topic-oriented Writing
January 27, 2006 : A report from JoAnn Hackos’ talk at the Central Texas DITA Users Group meeting January 2006
DITA and wiki combo
December 05, 2005: Darwin Information Typing Architecture, meet Wiki.
Darwin Information Typing Architecture - DITA (dih tuh)
November 04, 2005: Roundup of the DITA reading I’ve been diving back in to lately.
Writing End-User Documentation in an Agile Development Environment
This article was original published in the June 2007 issue of the CIDM Best Practices Newsletter. It is re-published in its entirety with the permission of the Center for Information Development Management.
In this article, we examine an increasingly popular development methodology from the Extreme Programming family—Agile development—and how technical writers can operate successfully in this methodology. We answer the first questions technical writers might ask when assigned to an Agile team:
- What is Agile development?
- How does Agile development affect my role on the team?
- What are the best methods for succeeding as a team member with this software-development methodology?
The experiences we discuss come from using Agile and a related methodology, Scrum, in creating enterprise software, like database administration tools, rather than Internet applications like Yahoo! Photos. This distinction is necessary because of the vast differences in the length of release cycles; enterprise software teams deliver in three to nine month cycles, while some Internet software teams deliver in cycles as short as two weeks. These differences mean that the implementation of Agile development varies greatly. Now, let’s look at some guiding principles of Agile development.
Agile Development Defined
The main principle of Agile development is to develop robust software rapidly with minimal expense and investment in detailed, up-front design. “Robust” and “rapid” are manifested in the use of iterations, or short development cycles (usually 2–3 weeks), in which a particular piece of the software is developed, tested, and documented. A development cycle built on iterations allows for rapid and continuous delivery, and it provides agility and flexibility that are missing in more traditional development methodologies. Problems are quickly discovered, and teams can either immediately correct a problem or eliminate an affected feature altogether without wasting design work that would have occurred in traditional methodologies, such as waterfall.
The Agile methodology is part of a large family of development processes and has no single, prescribed method. Many companies create their own Agile methods while using some of the original ideas and principles defined in the Agile Manifesto (http://www.agilemanifesto.org/).
A basic tenet of Agile methodologies is “Working software over comprehensive documentation,” meaning that internal design and specification documents are minimal or non-existent. Many technical writers struggle to be fully functional in such a development environment. Writers have traditionally relied on design documents to get a “big picture” of the product—what it does and how it works. The amount of internal documentation varies widely among Agile teams. Some teams do not even produce a list of product features, relying instead on their Agile planning software to act as a repository of the list of stories and tasks to be accomplished in each iteration.
Another tenet of Agile, “Individuals and interactions over processes and tools,” can make writers feel marginalized when determining how best to function in the team. Fortunately, the best Agile teams understand the value of end-user documentation or can be shown that an integral part of creating successful, working software is excellent documentation written in a tightly collaborative environment. In such an environment, the technical writer can adapt and even shine.
The Language of Agile Development
Often the most intimidating part of learning anything new is grappling with a new vocabulary, and Agile is no exception. Following are some basic terms that are used frequently in Agile teams:
- Iteration: A period of time during which the software is programmed and at the end of which the quality assurance (QA) testers verify that the software is working as expected.
- Stand-up: A daily meeting in which the progress of the software development is communicated.
- Story: The business need that defines what the software will do for the user. Stories are usually sized so that a single iteration is enough time for development, and they are usually written as “role can do task” (for example, “An Administrator can add a new User”).
- Task: Defines all of the subtasks for a single story. For example, for the story “An Administrator can add a new User,” one of the tasks might be “Connect the new component to an existing security component.”
- Backlog: A repository for stories that are targeted for release during an iteration.
How Does Agile Affect Your Role and Processes?
As part of an Agile team, you are expected to tell the team what you will deliver at the end of an iteration. Working in iterations has a definite affect on the scope, content, and presentation of your deliverables. You must be prepared to communicate your status daily because many Agile teams track progress on all stories and tasks daily.
Some techniques and certain deliverables are well suited for documenting products that are developed in an Agile environment:
- using a topic-oriented approach such as the Darwin Information Typing Architecture (DITA) or Information MappingTM
- leveraging user stories to produce task-oriented documentation
- applying minimalist principles
- participating as an active team member
Topic-oriented writing
Most writers are familiar with topic-oriented writing: authoring concise, self-contained units of information about a specific topic. Topic-oriented writing is a defining aspect of Information Mapping and DITA. In Information Mapping, complex information is broken down into basic components, and then the “chunks” of information are structured in a reader-friendly way. In DITA, information is categorized into concept, task, and reference topics. Such categorization makes sense in an Agile environment, in which “the right documentation at the right time” is the main goal for all documentation, end-user and internal.
In addition, DITA maps offer just-in-time assembly and output generation of documentation, which provides a huge advantage when creating Agile documentation. In an Agile environment, changes that make the software better, even at the end of an iteration, are welcomed and encouraged. But if a new function is eliminated from an iteration after you have already documented it, you just remove those topics from the DITA map for that iteration’s build. Keep those topics for the next time that feature is worked into a user story, and you become the hero when you link those topics in a new DITA map and generate output.
Translating User Stories into Task-Oriented Topics
In an Agile environment, development is driven by user stories, which define the tasks that end-users want to accomplish with the software. User stories must be customer-focused, succinct, and testable, and writers can leverage them to create user-focused, task-oriented documentation.
Task-oriented writing not only complements development’s use of user stories, but it is an absolute necessity given short iteration cycles and an often limited number of writing resources. The requirement to create installation and configuration information and solid procedural information (probably in an online Help system) often leaves little time in any release cycle to create much conceptual or best practices information. Such information can, however, be produced following a particular release cycle. The focus on tasks within a cycle, however, helps writers achieve minimalism, another technique particularly well-suited to documenting in an Agile environment.
Just-In-Time Documentation Also Means Just Enough
Minimalism in technical documentation has been advocated since IBM’s John Carroll wrote The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill in 1990. Minimalist principles are especially relevant when you adapt Agile methods to produce working documentation that complements working software at the end of short iterations. For example, you should avoid wordy overviews that are not task-based, and you should not even document obvious procedures such as how to cut and paste text or print reports.
The Importance of Team Spirit
Being an active member of the Agile team is crucial to a writer’s success. The lack of internal documentation makes full participation in the team an absolute necessity. Your awareness of hallway conversations and impromptu white board drawings about changes to the GUI, for example, could mean the difference between completing your stories or tasks within the specified iteration or not. The need for such camaraderie obviously must be understood and embraced by the developers and testers on your team.
Ideas for Best Practices
Having survived and thrived during releases using Agile methods, we have a few ideas for best practices, as well as pitfalls to avoid:
- You will be most successful if you are dedicated to a single Agile team, not a resource shared by several Agile teams. This focus enables you to attend all meetings, like the daily stand-up, where you can gather information and overcome roadblocks.
- Encourage and embrace the face-to-face communication that is a driving force in Agile.
- Locate your workspace near your developer and QA teammates if possible. If you cannot work physically near your Agile team, find ways to communicate as personally as possible in real-time, such as using Instant Messaging or web cameras with video conferencing.
- Agree with your development team on two key points:1. should the documentation tasks be included in the development team’s story or housed under a separate, documentation-specific story?
2. how many iterations can the end-user documentation lag behind the development team’s completion of a feature? - Write user stories for documentation that parallel the user stories that are being used to build product features. An example user story for documentation might be “A DBA can read online Help to learn how to manage licenses.” An alternative is to create documentation-specific tasks that are included under the development team’s user stories. For example, the development team might have already created a story called “A DBA can manage licenses”; as the writer, you can simply add a documentation task to the story. Another idea is to house all documentation stories and tasks under a parallel project, so that you can easily estimate documentation’s velocity.
- You must have access to the same planning tool that the Agile development team is using. This tool may be software based, such as Rally or XPlanner, or it may be index cards on a cork board. The ability to create entries gives the documentation tasks equal visibility and footing with development and QA tasks related to each user story. In some environments, the planning tool is the only place to see a comprehensive list of the product’s planned functionality, as represented by the stories.
- Request that all user stories be stored and accurately maintained in a single place, which will most likely be the Agile planning software. Ideally, the product manager or development team creates a product feature list or some document that states all of the product functionality.
- Write a minimal documentation plan so that you can focus on story planning and end-user deliverables. The documentation plan could list the key contacts, release theme, top stories, dates, and your expectations and assumptions.
- For each user story, ask the QA team to create an equivalent task for reviewing the online Help or other documentation.
- Request a “hardening” iteration in which you can complete final tasks for your deliverables—for example, check index entries on final assemblies or determine the optimal organization for a table of contents. Final user stories for documentation might end up in a “hardening iteration” that includes technical reviews.
- Use the backlog to house documentation tasks. First, pull high-priority, low risk items from the backlog into an iteration, and then return to the backlog for lower-priority or higher-risk items in another iteration.
- Keep your documentation task-oriented, in line with the user stories that are promised with each iteration. If you want to take task orientation to the next logical level, write your end-user documentation in a topic-oriented way with tasks having supporting concepts and reference topics, much like the DITA prescription.
Conclusion
Just as programmers employ Agile techniques to improve their deliverables, technical writers can employ complementary writing techniques to become an integral part of delivering useful software. End-user deliverables that are task-oriented and help the user perform at an expert level become a necessary and valued part of the success of a product developed using Agile methods.
Bibliography
Beck, et al., Manifesto for Agile Software Development http://www.agilemanifesto.org
Broderick, Stacia and Melody Locke. “A Tale of Two Writing Teams.” agile, pp. 295-304, AGILE 2006 (AGILE’06), 2006.
Cohn, Mike. Agile Estimating and Planning Prentice Hall PTR, 2005
About the Authors
Tana Berry
Senior Technical Writer
Database-Brothers, Inc.
tana.berry@database-brothers.com
Tana works as the only technical writer at Database-Brothers, a small company with a focus on database auditing and performance products. She has enjoyed working as a technical writer for more than twelve years and has been an active team member on an Agile team for a year. Tana loves Agile because it forces the writer to produce lean, task-oriented documentation with the end-user always kept as the focus.
Anne Gentle
Senior Technical Writer
BMC Software
anne_gentle@bmc.com
http://talk.bmc.com/blogs/anne-gentle
Anne Gentle works at BMC Software where she writes technical deliverables ranging from user manuals to online help to white papers. BMC has many product lines adopting Agile development methods and the product Anne now writes for, Configuration Management, has recently become Agile. Known to enthusiastically discuss communication topics ranging from blogging to wikis to XML-based information models like DITA, she sees DITA as an excellent gateway to more Agile documentation.
[digg=http://digg.com/software/Writing_End_User_Documentation_in_an_Agile_Development_Environment]
