Agile Technical Writing Basics

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 at the end of every iteration.
2. Confusing the 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 latter's absence - it is simply reduced to the required minimum.
3. The principles and values of the Agile method aim to produce 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 the 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, through such work can sometimes be challenging.

With the agile methodology applied, organizations can lower their 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 an agile way, the author often gets early feedback from users, right after each iteration, so improvements are made rapidly. Frequently help files are put on the 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 an 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 the 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 upon 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 reason.

Possible complications in Agile projects

If the 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 the main features is done nearly at the end of the developing cycle.
• Sometimes combination of several functions by single person is challenging.
• Developing help files demands a 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 a creative kind of activity and such a flexible way of technical communicating may seem a little fuzzy, there isn't any lack of discipline. It's assumed that you self-organize, as well as the whole team. Even 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, 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 in your manual 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 the advice is to arrange a special section for skilled users or to include several areas, 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 an all-in-one instrument that contains everything you need. One of my preferable tools for working in an Agile environment is Dr.Explain as it allows to concentrate on content, has a relatively simple interface, and due to this, has a 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 to export to various formats. Content of help is often modified with the 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 it is for, feel free to ask developers all about it, as it's essential 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 a 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: https://www.drexplain.com

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

See also

• Why software documentation needs index and how to make it work efficiently
• Software Documentation in Scrum Projects
• The Hidden Power of Online Manual