How Technical Writers Can Benefit from Agile Development


*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

The main principle of agile development is that all members of a product team sit and work together, developing code, writing documentation, testing, and providing quality assurance. Technical writers benefit from this early involvement because documentation is considered part of the product, and documentation development time is factored into the product release.

Agile development increases the quality of deliverables and helps technical writers cope with change more efficiently. Often, development and documentation work on the same problems at the same time. When the whole team takes responsibility for quality, the quality of the product goes up.

Here are some of the basic terms used in agile teams:

  • Iteration — A period of time during which software is programmed and at the end of which the quality assurance (QA) testers verify that the software is working as expected.
  • Stand-up — A daily meeting in which the progress of the software development is communicated.
  • Story — The business needs that define what the software will do for the user. Stories are usually sized so that a single iteration is enough time for development.
  • Task — Defines all of the subtasks for a single story. For example, for the story “An administrator can add a new user,” one of the tasks might be “Connect the new component to an existing security component.”
  • Backlog — A repository for stories that are targeted for release during an iteration.

As a technical writer, you will be most successful when you are dedicated to a single agile team, not a resource shared by several agile teams. This enables you to attend all meetings, where you can gather information and overcome roadblocks. You can also agree with the development team on how many iterations the end-user documentation can lag behind the completion of features.

The best agile teams understand the value of documentation and that an integral part of creating successful, working software is excellent documentation.

Have something to add? Please share it in the comments.

Getting to the Point When Writing for the Web

By Leslie Brown

Writing web copy is different than writing copy for print material. I’ve written both, and here are some of the things I’ve learned from different sources about writing for the web.

Readers take only seconds to assess whether a web page is worth pursuing or not, so you can’t linger on a thought. Get to your point quickly by making each word count.

1. Keep it short.

  • Use short words, short sentences, short paragraphs, and short pages.

2. Keep it simple.

  • Include only one or two ideas in each short paragraph.
  • Use simple language and common words so readers have to scan less to determine what a page is about.

Continue reading

Some Best Practices When Writing Help Documentation


*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

If you are planning to create online help documentation and want to make sure you end up with one that is truly helpful, here are three best practices you can follow to make sure it is:

  • Tailor it to users who have with varying skill sets and goals.
  • Review, test, and update it for accuracy.
  • Create context-sensitive topics.

Keep different users in mind

You can’t always predict what every user will know or want to know about any product. On one hand, if you oversimplify help steps, users might get confused. If you provide too much detail, they might get frustrated or bored.

One way to alleviate this problem is to divide help topics into several different types that target users at different skill levels by varying the kind and amount of information you provide. For example, you might have an overview topic, such as a definition of a specific system function, and then provide a link to all of the tasks related to that function within the overview. That way, users get just the specific steps they want.

The key is to allow users to navigate the help documentation to find (or avoid) as much detail as they want.

Continue reading