Agile Technical Writing Basics

By Ksenya Mizinova, Technical Writer

If you want to know what exactly Agile methodology stands for, you should check out several Wikipedia pages and specialized blogs, but the essentials can be described in a few words. Agile relies on communication between individuals during the overall process of development; working software is considered the best measure of team activities, and changes in customer's requirements are always welcome. Software is produced in iterative way: it is released once in a small period of time and every release includes new features.

Unfortunately, nobody wrote instructions for Agile technical writers, so peculiarities of profession need to be studied out.

Key points of Agile

Agile methodology can be perfectly applied to the process of technical writing. There are several differences though.

1. The main thing that describes agile tech writing is that making documentation (as well as developing software) should be done in small pieces and produced along with application in the end of every iteration.
2. Confusing second value of agile ("Working software over comprehensive documentation") does not actually refer to end-user documentation but to internal documentation. And even this does not mean the absence of the latter- it is simply reduced to required minimum.
3. The principles and values of the Agile method aim to producing high quality software that would fit market demands, so agile teams are extremely versatile. It is achieved by:
   • Transparency of project. For example, tech writers can observe developers' progress by viewing issue tracker for the quickest way of documenting just added features.
   • Small teams. This refers both to teams of developers and teams of tech writers. All participants are highly involved and motivated to do their best.
   • Several responsibilities of each team member. As for writers, besides actual tech writing and documenting, they often function also as first testers and link between the outer world and developers.

Benefits of Agile approach

Organizations, as well as participants of the process, can benefit from using Agile.

There are great opportunities for professional growth though such work can be challenging sometimes.

With agile methodology applied, organization can lower its expenses by producing cost-effective documentation. Because of incremental way of delivering help files, the whole help rarely has to be fully rearranged. Everything is done practically on the fly. With documentation produced in agile way, author often gets early feedbacks from users, right after each iteration, so improvements are made rapidly. Frequently help files are put on wiki so they are available to everyone for editing. It works in some cases though it is rather hard to control.

When applying Agile is not a good idea

As you can see, Agile methodology is exceedingly powerful tool, especially considering that along with small organizations it is used by Google and Microsoft. On the other hand it still does not fit some types of teams and projects. Such cases are:

• Customer's conviction in permanence of requirements. Such clients will likely pick teams that use Waterfall-like development strategies.
• Lack of trust and reliance among the participants. Since Agile methods are built up on close communication and interaction between members, it would be a better solution to use conventional methods if employees are better workers as individuals rather than team members. For obvious reasons Agile will not suit cross-cultural teams either.

Agile may not fit the project type itself for some reasons.

Possible complications in Agile projects

If decision on using Agile is already made, be aware of problems you may face:

• It's important to come up to every release with all key information already documented. It may be hard if one of main features is done nearly in the end of developing cycle.
• Sometimes combination of several functions by single person is challenging.
• Developing help files demands good program environment which is often difficult to choose.

And of course some minor problems that you can never predict will occur from time to time.

How to make life easier

Plan things out

Despite the fact that agile tech writing is pretty much creative kind of activity and such a flexible way of technical communicating may seem a little fuzzy, there aren't any lack of discipline. It's assumed that you self-organize, as well as the whole team. Even a draft planning will help.

First, you need your day to be scheduled properly. For example, you should take time to respond to users' comments on your documentation, to read RSS feeds on topics you're interested in, chat with other tech writers, and actually do some technical writing.

Before writing application help, you need to define the following information:

• type of document,
• target readers, amount of their knowledge about product you're going to describe,
• key points to cover,
• what style to use.


Estimate stages of writing. For example:

1. Make plan of help files.
2. Let the person in charge add remarks and corrections.
3. Update and correct the plan.
4. Start writing the documentation.
5. Modify it during the process if necessary.
6. Send completed documentation to person in charge, correct and modify.

Repeat several times until your piece of work is perfect. Don't forget about timing budgets.

Consider most users' demands

If you are documenting some complicated software, you should not put in your manual everything up to tiny details, because inexperienced users won't understand the essentials and how to perform even the simplest tasks. On the other hand such elementary help will not match advanced users' needs. So advice is to arrange a special section for skilled users, or to include several sections, one for every topic of documentation.

Get feedback

Another method of making help better is getting feedback from users. Comments and e-mails suit perfectly here.

Get your results checked

Try exchanging your pieces of work with your colleagues. The person who sees it for the first time will likely find misprints and logical inaccuracies.

Pick the right tool

Regardless of what you are to document, it is essential to have all-in-one instrument that would contain everything you need. One of my preferable tools for working in Agile environment is Dr.Explain as it allows to concentrate on content, has relatively simple interface, and due to this, has short learning curve. Along with this it helps to simplify the most time consuming stages of help authoring like screenshot annotating, and I also like the opportunity of export to various formats. Content of help is often modified with Agile approach, but it can be efficiently managed by setting topic statuses.

Ask questions

If you can't figure out how particular product feature works or what is it for, feel free to ask developers all about it, as it's extremely important to deliver correct information to end users.

Update and share your knowledge

It's extremely helpful to read what other tech writers publish (in blogs or single articles). Try to learn from the mistakes of others. Comment and share your experience, because you will become skilled tech writer eventually and your know-how will help other people. Consider blogging yourself.

Good luck in becoming a successful tech writer!





Article Source: http://www.drexplain.com

You are permitted to reprint this text as long as it includes copyright notice and direct link to our web site.