Mobile and Agile: The Floating Writer's Survival Kit

By Alyssa Fox and Meredith Kramer

---

Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

• Introduction
• Making the Transition
• Gaining Clout on the Product Team
• Planning the Release
• Creating User Stories
• Planning Iterations
• References

Introduction    

Agile development is a popular methodology used by software companies. When making the transition to agile development, technical writers can face several challenges when floating among multiple project teams.

As a floating writer, gaining clout and presence on your product teams is essential to success on those projects. Making your teams aware of your interest and need for information helps them remember you when you are working on another project.

Release and iteration planning is always vital in agile development environments, but even more critical when dealing with multiple projects.

Agile development was developed for in-house products, and then adapted for use by software companies. Originally, the methodology did not include documentation, but many organizations have figured out how to use it effectively and adapt it to their needs. However, even when product teams use this process successfully, it assumes you have resources dedicated to each team.

Businesses today are cutting back and doing more with less. People have more to do and less time and budget with which to do it. In software companies, one way this can manifest itself is in resources moving among multiple projects. When we began using an agile development process, we searched far and wide for information about how to work using that process when working on multiple teams. What we found was that most of the writers out there working with agile development were dedicated to one product team. As floating writers, we have unique challenges in agile development.

At NetIQ, the members of our Information Development team move from product team to product team. We have leads on a few product teams that generally don't move around, but for the most part, our team members work on at least two projects simultaneously. While the flexibility of our team members can be beneficial, it can also be challenging to plan for and execute work on multiple teams. This paper describes how technical writers can smoothly transition to and continue to use scrum agile development when they float among several cross-functional project teams.

Making the Transition    

Making the transition to agile development takes time. Regardless of which development process you're currently using, it will likely take several iterations, and possibly even a release or two, for your project team to feel comfortable with the new processes and way of life.

New Terminology

Agile development uses specific terms. Some of these terms and their descriptions are below.

Agile development

A development process that promotes iterative development, testing, and documentation of each feature/function.

Scrum

An agile development approach that emphasizes close communication through daily stand-up meetings. Scrum is intended to increase speed and flexibility in the development process.

Scrum master

The team member who facilitates scrum meetings and works to remove blocks that prevent team members from proceeding with their work.

Iteration

A short period of time in which a full software development cycle occurs: planning, design, development, testing, and documentation. Iterations typically last from 1-4 weeks. The goal is to have a potentially shippable product at the end of each iteration.

Backlog

The repository for all requirements and wish list items for the project. It is useful if the backlog contains rough estimates for the items to help with prioritizing during regular planning and review times.

Capacity

The maximum amount of hours a team member can work on a project during one iteration.

Design Documents

While agile development de-emphasizes design documentation in favor of working software, by no means does that mean all documentation is done away with. Comprehensive specification documents are replaced with shorter, more fluid documents such as user story documents and paper prototypes. Agile development involves working closely with customers to ensure you are developing what they ask for, and allows for refinement and rework along the way. A user story document describes what the user story is to do, acceptance criteria for the user story, and any additional information useful to QE and Info Dev.

When writers move on to a project for an iteration or two, they can get bogged down in a lengthy and sometimes complex spec. It's much easier for them to pick up three or four user story documents to read that apply just to their assigned user stories.

Adapting Your Review Cycle

When we used the waterfall process, we used a review cycle that included three drafts of each book: a first draft, an approval draft, and a quality edit draft. The first draft and quality edit draft were internal to Information Development. All of these drafts happened toward the end of a software release cycle, and were not reviewed by anyone outside the Information Development team until the project was feature complete and all features were documented in one fell swoop. Unfortunately, the time when we sent out our approval draft for review by other functional areas such as QE and Development often coincided with their busiest times of the release cycle--testing the product and fixing bugs.

With agile development, we now write documentation for a feature in the iteration it is developed and tested. On more mature products, we no longer send out the entire book as a first draft for ID review. Each time a feature is documented, that documentation must be reviewed by the ID lead/manager and by QE for technical accuracy before the team can close the user story. We still send out approval drafts, but for most reviewers, at that point it is simply a chance for them to see the book in its entirety, since they have reviewed all the new and updated parts of the book previously.

The benefits to this approach include the following:

• QE and Development no longer have to review an entire book (or more) during one of the busiest times of the release cycle.
• Info Dev gets more thorough reviews since QE and Dev have more time during each iteration to review pieces of the documentation.
• The documentation is more technically accurate, and therefore of a higher quality, due to the more thorough reviews.
• The floating writer's capacity needed for an approval draft is reduced because most of the work has already been done in previous iterations. Therefore, if you have multiple books on multiple products, there is not as big of a hit all at once on your time.
• Since you are likely moving writers around on an iteration-by-iteration basis, if you need to bring someone in to work just on the approval draft, they have a more complete document with which to work. It will then take less time for you to train them to pick up the work, and less time for them to get up to speed and get moving with the work.

Gaining Clout on the Product Team    

Agile development relies heavily on frequent and clear communication. It might seem like communication will not be an issue for us because we are professional communicators. However, often essential communication is thwarted by preconceived ideas of what a technical writer does or can contribute to the team.

Speak Up!

It is imperative you speak up in meetings and take the initiative to get involved in all aspects of the product development. Ask lots of questions. If you see something in a design meeting that doesn't make sense to you, or you think there's a better approach, say so. Don't be intimidated by the fact you're not a developer. It's our job to look at the product from a user's perspective. If a GUI is difficult to use, let the developer who's coding it know. If you find out planning meetings are happening without you present, talk with the ones holding the meetings and make sure you're invited in the future.

Scrum meetings are your chance to communicate with Development and QE on a scheduled, regular basis. It is important to give and get detailed, specific information during these meetings. If you don't receive the information you need, ask direct questions to solicit greater detail.

Sample Scrum Topics

For example, saying, "I'm working on the User Guide" in a scrum meeting is not detailed enough. A better description might be, "I'm creating a new chapter in the User Guide for Feature X. I've talked with Development and received all the information I need to complete the draft, but will go back to them tomorrow for them to take a look at what I've got to ensure it's technically accurate."

Another example of a vague scrum topic is saying, "I'm creating the help for Feature X." This statement does not provide enough information or let anyone else on the team know if you need help or additional information. A better description could be something like the following: "I am about done creating the help structure for the wizard Feature X uses. Developer Sally, I'll need to get with you to show you what I did in the mapping file so we can hook up the help to the wizard page code. I'm also adding these topics to the .chm file's table of contents."

Be Involved

Being involved in all areas of the product development is crucial to your success as a writer on an agile development team. This level of involvement ensures you are tuned in from the beginning and know the requirements, design, and thought behind the design of the software. Not only does this make you a more informed writer, it shows the other functional teams (Development, QE, etc.) you are serious about learning the product itself and gains you invaluable respect.

Ensure you're involved in the following ways:

• Show an interest in the requirements, design, and thought behind the design of the product.
• Attend any and all release and iteration planning meetings. If you aren't being invited, invite yourself.
• Offer to help improve text in the GUI. At NetIQ, our Info Dev team is responsible for all text that shows in the product. Often it just takes some informational text or a better field name for the GUI to be much less confusing to a user.
• Be a usability advocate. Look at things from the user's perspective. Something may be completely clear to the developer, but that doesn't guarantee it's the best way to present it to the user. For example, a developer might code a window that asks if you want to automatically notify a user when a report has completed, and your choices are "True/False" instead of "Yes/No."
• Have the writer working on the feature interact with the developer and/or QE person working on the feature. Don't funnel all information through one person.

Take Ownership of Technical Accuracy

At NetIQ, the writers are responsible for the technical accuracy of the documentation they write. In order to take ownership of the technical accuracy of your documentation, there are a few key things to keep in mind. First, don't write just what the developers tell you to write or assume something works a certain way. Ask questions and gain your own understanding of how the product works.

At NetIQ, the Information Development team creates and maintains its own set of virtual machines on which we install and test the builds of our products. Owning our own installations of our products allows floating writers to quickly and easily access the product without waiting on QE to install the product for us. This quick access reduces the amount of time it takes someone to jump in and start learning the product.

You must understand the product to know if there's a technical or usability problem in the product. If you demonstrate a solid understanding of the product, the team trusts you more when you make a suggestion for change.

Serve on a Core Team

A core team consists of a lead from each functional area (Product Management, Development, QE, Info Dev, and Technical Support). The core team drives the project and serves as a system of checks and balances to ensure there is equal representation from each area. The core team makes the decisions for the project together.

Planning the Release    

When planning a release, think about your entire review cycle. The First Draft and Approval Drafts will coincide with active Development iterations, whereas the Quality Edit should occur during a hardening iteration so it doesn't affect Development and QE schedules.

Do resource planning on an iteration by iteration basis. Have a manager or lead look at resources across projects in order to provide the optimum load balancing.

Creating User Stories    

User stories define a software system requirement, or what you are building. When creating a user story, include enough information for all functional team members to perform their tasks.

Creating Good User Stories

When creating user stories, use the INVEST method to ensure the stories are ready for all stakeholders to begin working with them:

• Independent: Can be worked on without pulling in other stories, can be scheduled in any order
• Negotiable: Allows flexibility with engineering team, implies it is understandable (easy to pick up)
• Valuable: Frames stories from customer perspective
• Estimatable: Allows lead/manager to pull floating writers on to project based on their capacity and estimate of time needed for story
• Sized appropriately: Lets floating writers focus on smaller pieces and move on and off project more smoothly
• Testable: Lets floating writers see upfront what the feature is supposed to do and can write more thorough documentation

User Story Tasks

Tasks are broken-down items of work required to fulfill a user story. All tasks must be completed before you can close a user story. To ensure tasks are clearly defined, follow the SMART method:

• Specific: Helps in understanding and prevents overlap
• Measurable: To know when it can be marked as complete
• Achievable: Is it feasible and realistic?
• Relevant: Aimed at fulfilling the story
• Time boxed: Estimated work remaining. Will it be done within the iteration?

Planning Iterations    

When planning an iteration, determine the length of the iteration and the workload capacity of each team member.

Determining Capacity

When determining a team member's capacity, keep the following items in mind:

• Consider previous iteration estimates, if available.
• Include vacation and non-iteration responsibilities, such as meetings, customer support, and so on.
• Do not include the first or last day of the iteration.
• Ensure Development finishes early so Quality Engineering and Information Development have time to complete their user story tasks before the iteration ends.

When you serve on multiple teams, you could spend 4-5 hours per week in scrum meetings for each project on which you're working. Work with your lead or manager to spread out the workload in such a way that you can delegate scrum meeting attendance to others. Another option is to attend only the scrum meetings that pertain to your highest priority project at the moment. You can also ask the scrum master to send scrum status reports through email to help those who are unable to attend each scrum meeting for each project. While it's preferred you attend each scrum meeting for each project on which you work, sometimes it just isn't possible. Gaining clout and a presence on your team is that much more important in situations like this so people don't forget you when you're not there.

Sizing Documentation Work

You can create more accurate estimates by applying a standard number of hours per page of documentation written based on the level of source material. For example, if a task requires one new page of documentation with little source material, the task will take 6 hours. If you need to rework a page of documentation with some source information, it will take 4 hours.

Using a formula to estimate documentation work can make iteration planning much easier. You can plug in your tasks based on the information in the user story to quickly estimate the amount of documentation work required to complete your tasks. You then compare the number of hours required to complete all documentation tasks in the iteration to the total hours of documentation team member capacity.

References    

1. http://www.agilemanifesto.org
2. http://xplanner.org
3. "Managing Information in an Agile Environment," Robert Armstrong, Natalie Dyen, Ellen Pillsbury. Presentation at 53rd Annual STC Conference, May 2006.
4. "Agile and Doc," Toni Taliaferro. Presentation at 53rd Annual STC Conference, May 2006.
5. "Surviving as a Technical Writer in an Agile/XP Environment," Andy Sutton, Matt McDonough. Presentation at 53rd Annual STC Conference, May 2006.
6. Subramaniam, Dr. Venkat. Agile Developer Training Manual. September 2006.

---

Alyssa Fox is an Information Development Manager at NetIQ Corporation. She works across product teams to coordinate resources, processes, and schedules for agile planning and implementation. She received a B.A. in History from Texas A&M University and has been involved in technical communication for over 10 years. Alyssa enjoys projects that address the entire user experience from beginning to end, and has an avid interest in usability. She is also interested in developing junior team members and building cohesive, cross-functional teams that work together to deliver a product that is relevant to the user. Alyssa is a senior member of STC and has served the Houston chapter as Executive Vice President, Vice President of Competitions, Vice President of Hospitality, Banquet Manager, Banquet Arrangements Manager, and competition judge. Alyssa has spoken at STC Houston chapter meetings and has won awards in the local STC competition.

Alyssa Fox, Information Development Manager
NetIQ Corporation
1233 West Loop South Suite 1800
Houston, TX 77027 USA
713-418-5334

Meredith Kramer is a Lead Information Developer at NetIQ Corporation. She started her technical writing career after graduating from Texas A&M University in 1998 with a B.S. in Journalism. Meredith enjoys contributing to projects that provide information to users in a clear and concise way to help make their jobs easier. She has served on teams this year that have moved from the waterfall methodology to agile methodology and spearheaded efforts to promote Information Development in that transition. Meredith is a senior member of STC and has served the Houston chapter as Vice President of Hospitality, Technical Publications competition judging manager for the past two years, and competition judge.

Meredith Kramer, Lead Information Developer
NetIQ Corporation
1233 West Loop South Suite 1800
Houston, TX 77027 USA
713-418-5400

※ 모든 회원은 $15.00의 가입비를 지불해야하고, 미국을 제외한 기타 지역의 경우 별도의 우편요금이 부과됩니다. 캐나다의 경우는 $15.00의 우편요금, 그 밖의 지역은 $35.00의 우편요금이 별도로 부과됩니다. 요금은 연간회비 형식으로 지불하며 매년 12월 31일에 한 해의 멤버십 요금을 지불합니다. 중간 가입자의 경우 그 해 12월 31일에 가입한 달을 기준으로 1년 회비를 지불하며 이 때 가입 시점을 달로 계산하여 차감한 뒤 비용을 지불하게 됩니다.

(가입은 온라인과 오프라인 방식으로 가능하며 오프라인 가입은 STC 홈페이지에 있는 자사 양식(PDF)을 다운로드 후 인쇄하여 팩스나 우편으로 발송)


※ STC의 멤버 가입을 할 때 등급별 차등 요금을 지불하게 됩니다.(한국 지역 기준)

1. Classic 멤버십
테크니컬 커뮤니케이션과 인터콤의 인쇄버전을 볼 수 있는 권리가 주어지고 온라인 버전의 접근도 가능. STC의 멤버만 사용가능한 사이트의 접근도 가능. 그리고 STC 커뮤니티에서 2개의 지부(chapter), 1개의 지부와 1개의 SIG(Special interest group), 혹은 2개의 SIG를 선택할 수 있는 권한이 주어집니다.

기본요금: $80.00(per year) + 가입비: $15.00 = $95.00
1개의 SIG추가 시 별도 $10.00의 비용이 부과, 1개의 chapter 추가 시 별도 $10.00부과


2. Electronic 멤버십
테크니컬 커뮤니케이션과 인터콤의 온라인 버전 접근 가능. STC의 멤버십 전용 사이트 사용가능. 2개의 지부(Chapter), 1개의 SIG와 1개의 지부, 2개의 SIG 중 택일이 가능합니다.

기본요금: $75.00 (per year) + 가입비: $15.00 = $90.00
1개의 SIG 추가 시 별도$10.00의 비용이 부과, 1개의 chapter 추가 시 별도 $10.00부과


3. Limited 멤버십
인터콤과 테크니컬 커뮤니케이션의 인쇄버전의 구독과 STC 멤버십 전용 웹 사이트 사용권한이 주어집니다. 단 지부(Chapter)나 SIG의 권한은 없음.

기본요금: $70.00(per year) + 가입비: $15.00 = $85.00


4. 학생 멤버십
인터콤과 테크니컬 커뮤니케이션의 접근이 가능하고 무한의 SIG와 두 개의 Chapter를 선택할 권리가 주어짐. 또한 1개의 프로페셔널 Chapter와 1개의 학생 Chapter를 선택할 수 있음. 단 STC 선거에 참여권과 선거권은 없음.

자격조건:
1) 4년제 대학교, 전문대학, 기술학교 등에 등록이 된 자
2) 2학기 이상 혹은 그에 상응하는 과정을 이수한 자
3) 테크니컬 커뮤니케이션 분야를 준비하는 자

기본요금: $50.00(per year)

뻔한 논리같지만 TW로서 반드시 지켜야 하는 Rule입니다.^^
 
1. Paper is Permanent
-Mistakes don't go away.
-Errors destroy the credibility of the product and the company.
-You won't be there to verbally clarify things.
-Proofread and edit thoroughly!
 
2. Know Your Audience
-Make safe assumptions.
-Distinguish the user from the market.
-Tap internal sources (marketing, tech support, etc.)
-Get customer contact.
-Learn to deal with mixed audiences.
 
3. Highlight Hazards
-Find hidden hazards.
-Rank warnings by severity (warning, causing, note)
-Make hazard visual clear. (indent or group)
-Place warnings appropriately.
-Explain ramifications.
-List prerequisites.
 
4. Break It Out
-Always remember that users don't read blocks of text!
-Use tables for values and specs.
-Use numbered lists for procedures and instructions.
-Use bulleted lists for features and other non-sequential information.
-Use flowcharts for branching processes.
 
5.Don't Write "Blind"
-Never rely on second- or third-hand information!
-See it, touch it, use it.
-If you can't do it, you can't explain it.
-Think and ask; what they want is not always what they need.
 
6. Be consistent
-Decide how to refer to the product.
-Pick one technical term.
-Consider interface elements and actions.
-Don't forget style, fonts, and layout.
-Use a style guide!
 
7. Signpost
-If it isn't documented, it doesn't exist.
-If it isn't accessible, it isn't documented.
-Never make users read material that isn't appropriate for them.
-Use layout and typography to indicate relationships of elements.
-Add roadmap in online Help.
 
8. Don't Violate Standards
-Recognize the difference between a legitimate standard and a bad de facto rule.
---(You need a good reason to change a standard.)
-Go to the source for the certification and guideline standards.
-When no rule exists, UDSG!
 
9. Contemplate Before You Illustrate
-Do you really need it?
-Do you need all of it?
-Does it enhance the text?
-Does it confuse the reader?
-Is it placed properly?
 
10. Cut the Fluss
-Remember, fluff kills!
-Watch out for these fluff items:
  "If you want to, you can..."
  "You may at this point need to..."
  "It is recommended..."
  Please
  Might, can, choose to
  Vague languages (more, some, bigger, a lot)
-Where possible, use telegraphic style.

Become a Great Technical Writer
even if you are not a great writer

Are you contemplating or beginning a career in technical writing? Have you been asked to create the user guide for your company's software application? Have you been asked to hire and manage a writer?

Where do you begin? How can you get an interview when you have no experience? How do you know if the technical writer on your team is doing a good job or a poor one? Can you find out before you hire the person?

Technical writers (known as technical authors in the United Kingdom) translate and organize complex information into user guides that any person can understand and use with ease. But in the 16 years that I have been in the business, I have often found myself working with writers who do not really know how to write manuals or use the desktop publishing software, and with clients who are not entirely sure what to expect from writers. More often, I have had to clean up a documentation mess left behind by a previous writer. This asymmetry between expectation and output can create technical writers who unknowingly make the same costly mistakes year after year, and clients who regard technical writers as a high-cost, low-value drain on the company's bottom line.

This site, whether you are a manager or a technical writer, will get you all working on the same page. If you are a writer, you will see that technical writing requires skills other than the ability to write. In fact, it is possible to write great user guides even if you are not a great writer. You don't need to spell perfectly (I don't), and you don't need to know the difference between a dangling participle and a dangling gerund. But although you don't have to be a great writer, you will probably be happier in the job if you like writing and are a competent writer. If you find it difficult to organize your thoughts and put them down in writing, you might find the job boring, unpleasant, and unrewarding.

In fact, writing is only a fraction of what you will do as a technical writer. This site, therefore, does not show you how to become a great writer—many other sites exist to help you with your grammar and style—but it does provide you with information, skills, tips, and techniques that can help you become a great technical writer.

Notes For Managers
If you are a manager, this site shows you what you can expect from the technical writers on your team. Although this site speaks mainly to the writer, you will easily be able to develop from the information provided your own expectations and requirements for your writers. This site will also help you distinguish between good and bad technical writing and it will tell you what to look for when hiring a writer. In particular, you should read the first three articles below.

:: 관련 링크 ::
http://www.docsymmetry.com/index.html

"기술 전문 저술가" [技術專門著述家, technical writer]

정보 기기 또는 전자 기기에 관한 기술적인 내용을 일반적인 경향으로 알기 쉽게 설명하고, 과부족 없이 정보를 제공하기 위한 문서를 쓰는 사람.

엠파스 IT용어사전에서 검색한 것이다.

현재 내가 일하고 있는 직군이 이것인데.. 흔히들 메뉴얼 제작하는 것만 생각할수도 있다.
내가 일하고 있는 부분은 Component Software 를 활용하여 Application 을 쉽게 개발할 수 있도록
Guide 를 제시해주는 문서를 만들고 있다. 뿐만아니라 Software Engineering Process 중에 투입되어
개발자들이 설계문서를 작성하는데 Writing 이나 Documentation 관련된 부분에서 Support 를 하고 있다.  

Technical writer