During the last year, I decided to step out of my comfort zone and explore new things. I’ve moved away from focusing on agile, DITA, information development, and user interface design. I jumped in with both feet into social media, information architecture, SEO, online media, email marketing, web and graphic design, and product marketing. I’ve been flying solo in Marketing — with a part time resource to help with PR. It’s been an exhausting, but truly exciting year. I’ve learned a lot along the journey that I hope to share with you over the coming year.

Stay tuned!

As agile software development gains popularity and corporate budgets are tight, technical publications managers are becoming obsolete. In many organizations, the Director of Software Development or Director of Product Management takes responsibility for managing the writing staff. In many cases, these managers lack formal training and experience in creating publications and managing writers. This article is a guide for managers who lack experience in managing writers, but are responsible for ensuring the documentation is delivered.

To manage agile technical writers, it is important to understand how the waterfall and agile documentation development processes differ. This article assumes that you are following a pure agile software development process, as opposed to what I like to call “agilefall,” which is a mixture of waterfall and agile methodologies.

The Waterfall Process

When an organization follows a waterfall process, the writer and manager might receive one or more of the following documents: Market Requirements Document (MRD), Functional Requirements Document (FRD), and a Product Requirements Document (PRD) when the project begins. Using these documents, the manager and lead writer work together to create a project plan that defines the scope, cost,  resources, and schedule. At this time, the writer usually installs the product build, which is typically in an Alpha state. Furthermore, the manager or lead writer creates a documentation plan that includes the deliverables, scope, translation plan, resources, risks, assumptions, dependencies, build and source control details, and schedule.

When the writing process begins, the writers interview subject matter experts and then “go into their caves” and emerge several months later with a help system and/or printed documentation in the form of a draft. Normally, a weekly status report is delivered to the manager. When the documentation and product are close to completion, the documentation is delivered to developers, quality assurance, product management, and editing staff for technical and editorial review. Some organizations require a formal inspection of the documentation to ensure complete technical accuracy. After the team members return their reviews, the writers incorporate the changes and subsequently create final builds. For printed documentation, the writers work with a printer to coordinate the final book production.

The Agile  Process

When an organization follows an agile process, formal documents such as MRD, FRD, and PRDs are typically not available. These documents might be replaced with shorter “mini-specs” that describe each user story or requirement. Photographed white board sessions also serve as “mini-specs.” Larger organizations with several dependencies (such as translation, support, and marketing) might choose to create documentation plans, while smaller organizations do not require this level of detail.

Agile teams work in iterations, which are short time boxes such as two, three, or four weeks. A typical agile team consists of a scrum master, product owner, software engineers, QA engineers, usability engineer, and a technical writer. The team delivers working, tested, and documented code at the end of each iteration.

Typically, at the beginning of each iteration, the team holds a planning session. If the agile team does not have a dedicated writer, but instead a “floating writer,” the manager might attend the planning session instead of the writer. During the planning session, the user stories are sized. The sizing should include the estimation of documentation work. This point is important because one user interface change that takes five minutes of coding could require days of documentation rework.

Agile teams participate in daily standup meetings. Writers attend daily standup meetings, and they report the specific details about the progress of the documentation for the user stories on which they are currently working. At the end of each iteration, typically a review session and retrospective occurs. In some organizations, the writer performs a demo of the completed documentation at the sprint review.

As opposed to a final review of the documentation at the end of the release as in waterfall, at least one member of the team completes a review of the documentation for each user story during each iteration. Editorial reviews are performed at milestones during the release or near the end of the release.

Tips for Managing the Agile Technical Writer

• Structure your teams to have a dedicated resource on each agile development team, if possible.
• Reduce the amount of management required by encouraging self management practices, for example do not assign tasks. Allow writers to choose their tasks.
• Encourage writers to evaluate each user story and identify the documentation changes that might result. Keep in mind, some writers from traditional waterfall methodologies are accustomed to managers assigning their documentation tasks.
• Verify that writers are following an established style guide and any guidelines established by information architects.
• Mentor or assign mentors to junior writers.
• Do not deprive technical writers of information. In some organizations, lead architects’ time is considered so important that writers are not allowed to ask questions. This impedes progress.
• Consider that the documentation is part of the product, not an afterthought.
• Consider that the agile process does not always allow for editing and overall reviews. Scheduling a “hardening sprint” at the end of the release cycle  allows writers to test procedures, check indexes, and complete final edits.
• Encourage team members outside of the writing staff to participate in the review process.
• Ensure writers are working in parallel with development. Encourage “mini-specs” and ensure writers are involved in planning and design sessions.
• Ensure writers complete their tasks at the end of each sprint. If parallel work streams are not possible because of the nature of the product, ensure writers complete their tasks at the end of each subsequent sprint.
• If writers consistently miss deadlines, re-evaluate the sizing of user stories.
• Ensure a manager or writer attends an after hours standup meeting at least once a week if development teams are offshore.
• Ensure translation managers are kept up-to-date with project deliverables or assign this responsibility to a lead writer.
• Encourage writers to use source control instead of creating and building documentation on their local machines.
• If there are several writers on separate teams across a large organization that have cross-product dependencies, encourage members to meet at least twice a month to keep each team on top of project progress.
• When developers are focused on “back-end” work that does not affect the end user of the product, encourage writers to edit documentation, enhance indexes, and test procedures.
• If your team uses a WIKI to communicate team practices, encourage writers to develop information for it.

Competitions are open to all technical communication professionals. You do not have to be a member of STC to participate. An entry must win an award of Distinguished Technical Communication or Award of Excellence at the local level to qualify for submission to STC’s international competition. Austin is among one of the chapters offering a local competition this year.

For 2010, Austin decided to resurrect the local professional competition, after a three year hiatus. The chapter received exemplary submissions. The judging was completed on January 17 with excellent results.

To honor our follow professionals, join STC for an elegant evening at River Place Country Club. Everyone is invited — Non-members, friends, and adult family members are encouraged to attend. This is a great time to get together with friends and co-workers, network with other technical communication professionals, and honor our colleagues. We have a fun program planned, which includes a presentation from Dr. Hillary Hart, Ph. D. who does research in and teaches Technical Communication in the Department of Civil Engineering at The University of Texas at Austin.

The cost to attend our banquet is $15 per person, if paid in advance. You can also pay $20, which is payable in cash at the door. See STC Austin Competitions Awards Banquet for details about the awards banquet and payment information. RSVP is required.

My primary home and work computers are both MacBook Pros. I’m running VMware Fusion and Windows 7 on my work computer. So naturally, I was eager to download the trial version and check it out. My first “proof of concept” screencast captured video from my team’s web-based Customer Relationship Management application.

For the most part, I am pleased with the software (especially for a 1.0!), except for a few glitches:

It requires you to capture the entire screen, and then crop it down to your preferred size. This is a little tricky because you must make all your windows uniform if you are not recording the entire video from end to end (instead of transitioning several small videos).

The most frustrating aspect of the product is the lack of ability to remove background noise. I searched the website found this suggestion…

“Build a small box lined with foam to put your microphone in as you record, use pillows or blankets to muffle the noise, or cover your head with the blanket.”

I don’t believe this is an acceptable solution, and I doubt it would reduce the fan noise that is extremely distracting. I resorted to splitting all my audio and video and deleting all the audio. Instead, I used Audacity, which is an open source product to record the audio and remove the background noise. I saved each audio clip as a .wav file and imported each one into the project. You can download this nifty product here.

I will be further experimenting with the export formats, but so far QuickTime is the only output that met my quality requirements. I found that when I dragged the application from my MacBook Pro over to my Dell Monitor, when I dragged it back to the Mac laptop screen, it crashed every time. In fact, it corrupted my project and it wouldn’t open. Luckily, I created a backup.

Exporting a six minute movie to QuickTime seems takes a long time when I use all the default settings for the export. For example, it takes about an hour.

There didn’t seem to be a way to highlight mouse clips or add glowing effects to certain areas. Filters apply to the entire clip.

On the other hand, I’m pleased with the following items:

The timeline is intuitive and very easy to use. The snapping works very well for lining up the clips.

The SmartFocus feature is nice, which automatically zooms in on areas based on the action in the recording file such as cursor movement, menu selections, and the active window. However, it does not work well with shorter clips. They just stay zoomed in and don’t zoom out.

The QuickTime output is very high quality.

The UI is very intuitive. I was able to learn how to use the product in less than three hours.

The transitions are extremely easy to use.

Overall, it’s a good product, and you can’t beat the $99.00 introductory price. However, the removal of background noise might be a dealbreaker for me. If you have a good idea about eliminating fan noise from the audio, I would love to know about it.

See http://www.stcaustin.org/competitions/ for more information.

Lack of defined release dates.
In Waterfall methodologies, the leadership and teams define release dates. In agile, often times the development team decides when the product is ready to release.

Lack of colocation.
Localization teams are usually outsourced and/or located offshore. When colocation is one of the key principles of agile, challenges arise because communication suffers.

Constantly changing business requirements.
In agile, change is common and welcomed. However, constant changes result in high translation costs and missed deadlines.

Lack of communication outside of the core agile team.
Many agile teams communicate splendidly with the members of their core team and work outside of the corporate box. Translation teams work in a more traditional manner and do not regularly communicate with the agile team.

At my previous company, our agile team successfully delivered documentation in four languages (English, French, Japanese, and German) simultaneously for one product. I would like to share the best practices we followed in order to deliver our products and documentation on time and within budget.

Designate a team member to interact with the translation managers on a regular basis.
In my experience, I found that the Information Developers/Technical Writers are a great choice for this role. The documentation is largely more difficult to translate than the user interface. This resource can manage both aspects, and obtain information from developers or QA engineers when needed. A meeting once a week with the translation managers is sufficient.

The product owner, product manager, or program manager must complete a release plan with a designated release date.
It is nearly impossible to plan localization with outside vendors without a good idea of the size of the work. Translation managers are required to complete Statements of Work and determine budgets.

Analyze the user stories or requirements in the release plan and provide accurate estimates of work.
Translation managers must have accurate estimates to plan translation projects.

Ensure Developers separate text, labels, messages, and other locale-sensitive objects from the source code and complete text strings during each iteration.
Developers must complete the translatable strings during each iteration. Consider using XLIFF. For more information, refer to http://g11ntoolkit.sourceforge.net/userguides/XLIFFEditorUserGuide.html#overview. Translators can regularly monitor when the strings are new or modified and translate strings as the product is in development.

Create a localization plan or documentation plan that includes translation drop dates.
In my experience, I found that three drop dates during a six month release is optimal. We attempted to deliver translation drops for a three month release at the end of each iteration (three weeks). There is too much rework when you deliver during short iterations, which results in increased cost.

Ensure you implement a “hardening iteration” before your release.
You must cut off user interface changes prior to your last iteration to allow for testing of the translated user interface and documentation.

Flag changes in documentation during each iteration.
If your organization uses a Content Management System, it should handle the complex workflow that is necessary for translation. If you are using source control, such as Subversion, attach metadata (or “properties”) to files and directories to flag the files or directories as “ready for translation.”

Plan a release retrospective with the translation managers.
A release retrospective helps to resolve an issues and continuously improve the process.

Take note, you can implement agile with paper index cards, post-it notes, and physical cork boards. As agile has “grown up,” numerous software tools emerged to manage this process. Many companies are using GreenHopper to manage story cards within JIRA. Other companies are adopting Rally, VersionOne, Scrumworks, TinyPM, or others.

As an Information Developer who was the primary author for a product that managed agile processes for an enterprise ALM software company, I’m sharing my thoughts about the pros and cons of adopting agile software development tools.

Pros

Visibility for Management – Management can quickly access the software to view a virtual cork board and also view key metrics, such as a burndown chart. Of course, take your goals into consideration. Visibility into the software development process might not be an issue for your organization, especially if your organization is small.

Metrics – Metrics, such as the burndown chart, are easily generated. Management and practitioners can make informed decisions by evaluating the organization’s key metrics.

Supports Geographically Dispersed Teams – If your organization has members across many locations and telecommuters, a software tool might be necessary for success because it is always readily available.

Records History – History is easily accessible and data is backed up. Allows the team to access information about earlier releases and sprints to assist in making informed decisions.

Acceptance Testing – With the right tools, you can easily link artifacts for acceptance tests to user story acceptance criteria.

Supports Agile at the Enterprise Level – With multiple teams and a wide variety of stakeholders, the physical cork board and paper index card approach is not feasible. Agile software tools support multiple teams and multiple locations across the enterprise.

The “Cool” Factor – These tools look pretty sexy when you want to impress everyone at the sprint review.

Software is “Green” – All those paper index cards will be in a landfill someday.

Cons

Unproductive Metrics – Studies have proven that measurement drives behavior. When management gathers metrics from agile software development tools such as comparisons between team members, counter-productive behaviors might emerge.

Does not Promote Face-to-Face Conversations – Face-to-face conversations are important in agile. When you can find all the key answers within your software tool, you can have a tendency to avoid these conversations and jump to conclusions.

Promotes Geographically Dispersed Teams – Using a software tool allows users to access the information they need from any site. With co-location being one of the key factors for success in agile, this result might not be ideal.

Can be Cumbersome for Practitioners – When engineers are focused and they are required to open another tool to record the number of hours they worked on a task, it can become cumbersome. Most often, the data is not accurate because it is completed at the end of the day without much thought.

Simplicity Enables Teams to be Agile – When software becomes too complex, it inhibits the productivity of the team. Index cards and a cork board are the simplest tools. If you invest in a software tool, ensure it is not overly complex.

Physical Cork Boards are More Influential – Psychologically, a cork board full of index cards tends to have more influence on the actions of a team, rather than a virtual cork board which is hidden on a web server.

Cost – Many of the tools can be costly, especially if they are not suited for the team. However, open source tools and SaaS solutions are available. You can buy index cards and a cork board for under twenty dollars.

I’ve included some tips to help Information Developers accomplish working in parallel with product development.

Use a Topic-Based Approach
DITA is an ideal architecture for the agile Information Developer because of the topic-based approach. In DITA, information is categorized into concepts, procedures, and reference topics. Migrate away from book-oriented approaches with chapters and pages and provide user documentation with small chunks of information in separate topics. This approach enables you to write simple, straightforward, and lean user documentation. It provides the flexibility for rearranging topics as the functionality of the application evolves. It also allows you to quickly and efficiently get your work reviewed by subject matter experts because they can review just the topics that are new or modified.

Pay Attention During Planning Sessions
Planning sessions are not the time to check out and wait for Developers and Managers to tell you what needs to be documented. Listen carefully to the description of the user story. Picture yourself as the end user and visualize the type of documentation that the end users need to understand the new product functionality. Search the current documentation during the planning session to locate the areas that might require changes to help you size the user story. Ensure you have the latest build of the product installed and evaluate the impact of changes to the user interface. If the new feature greatly impacts the documentation, speak up. This allows the team to decompose the user story appropriately so you can fit the writing tasks into the current sprint.

Get Actively Involved in Design Sessions
In some organizations, Information Developers are not included in design sessions. If this is the case, get invited the meetings. Become a subject matter expert and contribute to the design. Ensure the team has a shared understanding of the new feature and volunteer to take notes. Share the notes on a WIKI and take pictures of the whiteboard during whiteboard sessions. Understanding the feature before the Developers write the code allows you to start writing the conceptual topics from the get go. If your team is lucky enough to have UX engineers, refer to their wireframes and mockups and start writing the procedural topics.

Encourage Lean Internal Documentation
Encourage team members to collaborate and write “mini-specs.” Mini-specs describe the high-level design of a feature. Mini-specs also include how the feature functions from a user’s perspective. A lean document that describes the feature and includes mockups allows you to write the user documentation before the feature is “code complete.” In many cases, you can complete the documentation before the Developers finish even one line of code. During this process, you inevitably discover issues with the software design. Discovering these issues early saves the headache of future rework for the entire team.

Work Closely with Quality Assurance Engineers
Collaborate closely with QA Engineers. Consider leveraging the documentation that is included in the tests.

Listen During Standup
Listen to the Developers’ status reports during standup. If a Developer states that he or she completed a feature, ensure it is checked in so you can install the latest build and see the product in action. Test your procedures and immediately distribute your topics to the team for review as soon as you complete them.

I’ve discovered that “no documentation” is not practical for medium or large companies that develop products with dependencies across multiple teams. When multiple teams are spread among many locations and time zones, the lack of documentation can diminish communication. Small companies with fewer than 50 or so employees who are co-located can function with little or no documentation because of the face-to-face daily interaction among team members.

In agile, the team members are expected to be self organized. They should decide the amount of documentation that is appropriate for the team. Of course, they should consider that face-to-face communication is more effective in many cases. In addition, they should keep in mind that most of the documentation is for external teams and stakeholders so it should not replace face-to-face communication among the agile team members.

Individuals who are new to agile have asked me the type of documentation artifacts that are useful when implementing agile in a medium-sized enterprise software company with multiple locations.

I hope you find this list useful.

Mini-specs
Describes the high-level design of a feature. Also includes how the feature functions from a user’s perspective. Includes mockups from Usability Engineers. Might also include database schema modifications.

Documentation plans
Outlines deliverables such as Installation Guides, Database Dictionaries, On-line Help, Context-sensitive Help, etc. Also includes a plan for localization, such as translation milestones and estimates of work. Includes risks and mitigation of risks. Includes open issues that affect documentation deliverables.

User stories
User stories replace the traditional MRDs and PRDs. A user story is a high-level definition of a requirement, but only contains enough information for estimation purposes. Capture user stories on a physical or virtual team board.

Tasks
Tasks describe how to implement the user stories. Capture tasks on a physical or virtual team board.

Code comments
Includes text added to source code, which describes the function of the code. Face it. Not all code is completely clear and unambiguous.

Retrospectives
Document the results of your retrospectives so you can ensure that you are continuing to improve your internal processes.

Tests
Tests can function as documentation. Consider leveraging the documentation that is captured in tests.

Consider that collaboration is key, and organizing the above artifacts on a WIKI helps the team communicate project details and project status to stakeholders and external teams. The WIKI is also useful when conducting sprint reviews for teams and stakeholders. It becomes a centralized “meeting place” for your project.