Developing documentation for agile

– Manjusha Nair

In earlier articles in this series, we have planned for our agile project, and we have gathered the requirements. Are you still wondering how we can actually write for agile? If you wonder how we can develop documentation that is release quality and free of errors, in just a couple of weeks, you are not alone. The shortage of time and an absolute lack of specifications documents worry most technical writers who are new to agile.

Let’s look at how we can overcome these obstacles and create effective documentation during a sprint.

Participate in sprint planning

Every sprint begins with a sprint planning meeting. You must be a part of this meeting and sit through the whole meeting till a plan is drawn. Why I say this is, you may feel a little left out and may not always understand technical discussions, but it is extremely important that you attend this meeting.
When you hear the developers discuss each item in the backlog that they are planning to take up in the sprint, you get a good idea of what you’ll be dealing with in the sprint. It also allows you to form a mental picture of the final product you’ll be documenting and gives you the confidence to be able to come up with estimates and timelines for documentation. Similarly, when you share your inputs, the development team appreciates what documentation teams do and this shared understanding of work goes a long way.

The to do list

Refer to the high level plan you created. This keeps you on track and guides you in achieving the desired results. Draw up a personal sprint plan just for documentation, it will keep you sane and on track through the sprint. This plan need not be elaborate – it could just be a list of the tasks you need to carry out in the current sprint with the times that you set yourself for these tasks. Also, jotting down what you need to do gets you prepared to ask the right questions and not appear clueless in the early stand up meetings.

Involve the team

You cannot work as an island in an agile project. Involve the team early on by taking real interest in what the others are doing, and showing them how documentation is important to the project. You can discuss the following points with your team:

• Will they be creating any design documents at all? If yes, by what time?
• How quickly can they share a prototype / wireframes?
• Are there any other tasks you can help with? (This depends on how much time you have.)

Use the user story

After you have read the user story and interviewed the developers, you have a high level understanding of the feature and where it fits with the other features. Now you can start writing the draft. This draft will surely go through a lot of changes before it can metamorphose into the final document that your end user would see.
The best documentation method that works for agile is task oriented writing. When writing, start from the user story as a base, which being task oriented by itself, will guide you in developing task oriented documentation.

Less is more

Agile is a very good way to avoid unnecessary fluff and concentrate on only what is needed. Documentation for agile projects needs to be to the point and concise. There is simply no time to include ‘just in case’ or unnecessary information. This means that you are not simply including information because ‘it is there’. You actually look at what works best for the tasks at hand.

Here are some tips for writing to the point:

• If something can be said in 10 pages, don’t write 20. If something can be said in 5, don’t write 10.
• Write in bullet points or steps. This cuts out the fluff.
• Write just enough background information to provide a context.
• Start with a skeletal document that covers the minimum information that users need to perform the tasks on hand, and then augment it as required.
• Keep diagrams and illustrations simple.
• Do not repeat any information contained in any other document – simply create a reference to it.
• Focus on the needs of the end user of the document. Do not pack in everything the developers think the documentation should include.
• Every document and every topic within the document should serve to fulfill a goal. Question each topic and each sentence, ‘what purpose does this serve?’ and only if you find an acceptable answer should you retain it.

Test the documentation

Remember to get the QA team to test the documentation alongside the software/product. This is a sure way to weed out errors and check if the help really helps. This can easily be done as you are writing the documentation at the same time that the development team is developing the application. There is very little lag, if any. Also, the documentation is concise and task based which makes is easy of the testers to test alongside the software.

Some things that may derail documentation, if not planned for:

• The engineering team may create small specifications documents for their reference, which might become available to you sometime during the sprint. You can use these to check for errors and strengthen your draft. But if not planned for, you will find it difficult to include new information at that point.
• You will probably get the first look of the UI towards the middle of the sprint. Considering that you have already been working on the draft, this obviously requires you to make changes to the documentation.
• The testing team’s inputs, which typically come towards the end, might also lead to changes in functionality.
• Technical teams sometimes take the ‘known defect’ route to beat time. In other words, they may ask you to include a few notes or caveats, because there is no time to fix the issues in the build.

You are working agile, which gives you a lot of freedom to explore new possible areas of work. You can help with labeling and micro-text, of course. But you may also find that you can help with testing, or if you are tech-savvy, coding as well. Agile does not define goals for anyone in the team, which means any of you can pick up any of the tasks on hand.

In an agile environment, you work as a part of the team and not in a doc-silo like most waterfall projects. If you keep up the pace and the quality, you can reap rich rewards: on-time, succinct, task based documentation is, of course, the tangible benefit; but apart from that, you also get to bond with the engineering team and form functional networks, which go a long way in helping you gain domain expertise and confidence.

About the Author

Manjusha Nair is a content specialist working with Infosys, Bangalore. She is passionate about innovation and sharing knowledge. In her spare time, Manjusha likes to write poetry and fiction.