Technical writing and documentation in an Agile environment

The challenge of writing user documentation in an Agile environment

Agile’s principles of incremental, rapid software development, with its cycle of frequent releases, can create challenges if you’re responsible for developing the online Help that end-users need and expect. Typically, you’re faced with very short timescales between each deliverable, little formal project documentation, and a very busy development team.

Do Agile projects need user documentation?

Ideally, a product will be intuitive, but often this just isn’t possible. In reality, products developed using Agile methods still need user documentation. Some of your users will get stuck, and some won’t understand your product’s conceptual model.

This means User Assistance – the embedded Help, onboarding screens, online Help, reference guides and Knowledge Base – should be seen an integral part of the product itself. Ideally, these should be delivered at the same time as all the other parts of the product. The user documentation should be included in your project team’s definition of “Done”.

Treating documentation as code

Treating documentation as code means applying software development techniques and tools to software documentation. Processes can be more closely aligned with the development process by using the same version control, repository and review systems, and even integrating the content with engineering code.

Collaboration between writers and developers can be streamlined by using lightweight markup languages and static site generators that are accessible to all, even customers. 

Cherryleaf can help

Cherryleaf pioneered the idea of using Lean and Agile methods in technical communication. The goal is to focus on maximising the value to the user, as well as minimising waste during production.

Minimum viable documentation

We’re not in the business of writing documentation that simply isn’t required. By using a technical communication method called Minimalism, we’ll focus on the content that the users actually need.

Fitting into your workflow

As well as the option of using our in-house team of Technical Authors, you can choose to have a contract or permanent Technical Author onsite continuously for the duration of your project. This gives you the opportunity to embed technical writing resource into your Agile teams.

If you want the content written in Markdown, pushed to Git, or created in another way that fits in with your existing development workflow, we can set up the writing process so it suits your needs.

Collaborative Authoring

Technical writing, and the tools used to create online Help and user documents, shouldn’t become a bottleneck. Some documentation projects are best done collaboratively, enabling everyone to create, share, discuss and update the information. We can work in a way that you and your colleagues are able to add content themselves. For example, your subject matter experts can record their knowledge into the authoring system, which we can then turn into user-friendly information.

Contact us

If you’d like to discuss your situation and explore how Cherryleaf could help you, contact us via this projects enquiry form.