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”.
Cherryleaf can help
Cherryleaf pioneered the idea of using Lean methods as a way for technical communication to adapt to the Agile environment. That’s because the Agile methodology is based on many of the ideas of the Lean methodology. The goal is to focus on maximising the value to the user, as well as minimising waste during production.
Improving the documentation process
Single sourcing content
The component-based technical writing methods we use give you the ability to create a single source that can be used across different media and multiple documents.
You can make a change in one place and see that change ripple through all the documents that use that piece of information within them. You can take these chunks of text and re-use them in more than one place. You can arrange them in different ways to create a range of documents.
What’s more, in some cases, we’ll find that content is repeated, and we’re able to reduce these to a single topic.
Automating document production
In some cases, it’s possible for us to employ automation to generate the documentation. A number of Help Authoring tools support command line publishing, and automated publishing is also possible with Content Management Systems.
Flexibility and responding to changes to the plan
Topics can be dropped in and out, as project plans change, with publication left to the end.
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.
We start each project by asking:
- Who really needs information?
- When do they need it, and can we phase it in?
- What is the purpose of the document?
- How can we shorten the time line by reducing the non-value adding wastes?
- What does the customer actually need and want?
- How can we improve the content easily over time?
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.
Reviewing and approving content
We can recommend tools that make it easy for anyone in your organisation to review and contribute content to your documentation. Managers and subject matter experts (SMEs) can edit and review topics, make annotations, and update content with a simple, easy-to-use interface. This can mean the reviews, and the subsequent publication and translation of content, can be carried out as each page is completed (rather than having to wait for the whole document to be finished off).
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.
If you’d like to discuss your situation and explore how Cherryleaf could help you, contact us via this projects enquiry form.