Atlassian’s Sarah Maddox has posted her slides from her STC Summit 13 presentation “Doc sprints: The ultimate in collaborative document development”. It’s a useful description of a documentation sprint and its benefits:
Research conducted by two Oxford academics (Why Your IT Project May Be RiskierThan You Think) has suggested that the private sector has almost as much difficulty managing big software projects as the public sector. It also indicated that some types of projects have put companies’ survival at risk.
Whereas government departments can experience almost permanent revolution, private sector processes, in general, remain fairly stable. So it’s depressing to learn one in six of the projects they studied was a “black swan” – with a cost overruns of 200%.
The causes include: technology that doesn’t work, the difficulty in accommodating the exception cases, managing large teams, changes to the scope of the project, dealing with legacy systems, changes in legislation, and failing to build a system that meets the users’ requirements.
The researchers recommend breaking projects into smaller, more manageable units and using the best possible forecasting techniques.
There’s an additional problem: systems that work technically can still fail. If the user does not understand how to use the system, or if they don’t understand the benefits of using it, your “successful” system can end up under-used. User Assistance (online Help, Getting Started guides, screencasts and so on) mustn’t be forgotten. It’s one of those final steps in a truly successful project.
We’ve been working on a white paper that looks at how User Assistance can be more effective and developed more effectively when you’re working in an Agile environment. The white paper should be published in the next few weeks, but here’s a sneak peek at one of the issues we discuss: the lack of time available for creating User Assistance.
Agile’s iterative release of products, and sometimes frequent changes to the functionality and the User Interface, can make it difficult to create the user documentation. The Technical Author can end up having to rework content they’ve written, delete sections on functionality that’s no longer part of the product, and add information on features that have been introduced towards the end of the project. If the Technical Author waits until the product has been completed, they can find they have very little time available for writing the user documentation.
So what can you do about this?
One of the strategies in the Agile methodology is to create documentation as late as possible. Is this actually a good idea?
According to Scott Ambler:
A common agile practice is to defer the creation of all deliverable documentation as late as possible, creating them just before you need to actually deliver them…Fundamentally, this strategy is to wait until the information has stabilized before you capture it in documentation.
The reason for this harks back to one of the “three wastes” of the Toyota Production System – the waste of muda. The goal is to eliminate the time spent on activities the customer will never receive or would be willing to pay for.
However, there may be situations where documenting late results in one or both of the two other forms of waste – muri and mura. Muri means overburden – overloading or making things too difficult for certain teams within the production process (and/or for the customer). Mura means unevenness – which can lead to unnecessary waiting time for certain teams within the production process (and/or, again, for the customer).
If the cost of these wastes is greater than the waste of documenting sections that are abandoned at a later stage, then it may make sense to abandon the idea of “document late”. In order to be able to make this judgement, it is essential Technical Authors measure both the value of the documentation (e.g. the productivity of the user, the number of support calls, the number of times it is used) and the cost of producing it. With this data, Technical Authors can then make a stronger case for modifying this practice within Agile projects.
Agile programming has grown in popularity, and it has lead to new challenges for those involved in providing User Assistance for those applications.
So is it time for Technical Authors to develop an equivalent method for developing content for these projects? Is it time to develop an “Agile authoring” methodology?
Such a method needs to complement Agile programming, but it may be a mistake to take Agile programming as the starting point for developing it. The developers of Agile drew upon the principles of Lean manufacturing, and perhaps Technical Authors should do the same.
What would we be likely to see in such a method? Here are some suggestions:
- One piece flow. Information is moved through the process in the smallest batches possible. For example, translators and reviewers receive content topic by topic (or chapter by chapter).
- Minimalist manuals. Only the information that adds value to the user, or increases their productivity, is included.
- Incremental publishing of content (and frequent builds of drafts).
- Documentation sprints through collaborative authoring.
- Rigorous testing and measurement of the value of the documentation.
- “Stop the line”. Authors have the right to stop the development of software if they spot a critical mistake or if they are overburdened with work.
- Separation of “look and feel” from content, to enable adaptation to change.
- Iterative updates to the content.
- Close daily cooperation and communication with the development team.
- Removal of “waste”, such as waiting for new information or overload of work.
- Buy-in and commitment from all the stakeholders of the value and need for the User Assistance.
What would you envisage an Agile authoring methodology to contain?
Addendum: A further point for the list:
- Creating information that reduces “waste” at the user’s end. In Japanese, there are the concepts of go no sen (reacting), sen no sen (a simultaneous response) and sensen no sen (preempting). Writers could aim for sen no sen or ultimately sensen no sen -providing information that preempts problems.
It was suggested I read The Lean Startup, by Eric Riess. This book outlines how the principles of Lean manufacturing can be applied to startup businesses, and software businesses in particular. For startups, it’s about how to figure out the right thing to build – that people will pay for – as quickly as possible. I’m still reading it, and so far, it is very good.
It begs the question:
Where does user documentation fit in a Lean startup, and can the principles of Lean be applied to User Assistance?
Let’s start by looking at the slide deck below, which outlines the principles of The Lean Startup:
Lean is an adaptation of the Toyota Production System. Toyota’s view is that you should focus on reducing waste to expose any systemic problems. The main three types of waste are muda (“non-value-adding work”), muri (“overburden”), and mura (“unevenness”, such as waiting).
There is also a Lean software development movement, emerging from within the Agile community. According to Wikipedia, its philosophy is everything not adding value to the customer is considered to be waste (muda). This includes:
- unnecessary code and functionality
- delay in the software development process
- unclear requirements
- insufficient testing, leading to avoidable process repetition
- slow internal communication
Does Lean = eliminate user documentation?
So let’s address a key question: is user documentation wasteful (to be eliminated), or does user documentation add value?
Under Lean, you should only document what customers tell you is absolutely necessary. This might mean, in a Lean startup, you only document 80% of the system. That leads to a new challenge for Technical Authors – knowing which 80% to document.
Ultimately, the purpose of User Assistance is also to reduce waiting (the waste called mura), because it’s there to help you when you get stuck.
The process of writing User Assistance should contribute by helping organisations identify the difference between value and waste. Technical Authors are able to provide developers with valuable feedback on the product. User documentation can also help by filling in “gaps”, avoiding the need to waste time fixing problems.
However, paper documentation and online Help arguably leads to waiting (mura), because the user has to stop in order to go to the Help. Instead a flow-based approach might be better – offering Help and assistance at the “point-of-need”.
I asked a client who uses the Lean Startup principles to develop their software, how user documentation fits into the model. They recommended:
- Don’t try writing a paper/PDF manual, as it will go out of date too quickly
- Don’t tie yourself to documenting before release in the traditional way, or you’ll become a roadblock. If you’re releasing quickly and regularly, missing something out of one version isn’t going to be the end of the world.
The need for validated learning
A key principle of the Lean Startup is “validated learning”, knowing where to learn and adapt quickly from your mistakes. It is, according to Riess:
a rigorous method for demonstrating progress that a team has discovered valuable truths.
Validated learning is lacking in technical communication, and the Lean Startup’s principles are another argument for measuring the outputs and value of what we create. This means using analytics, carrying out usability testing, and conducting A/B testing of the User Assistance itself. A/B testing of user guides is possible if your content is on the Web (and you’re using one of the authoring tools that supports A/B testing). Riess strongly recommends A/B testing as a useful method for learning . A/B testing can be used to improve the Help topics and information design. It can also be used to determine which content to prioritise – you could post blank pages for incomplete pages and see how many click throughs you get.
What do you think?
What do you think? Is a Lean Startup approach a good or bad thing for Technical Authors? Does the Lean perspective assist in positioning the role of User Assistance within an Agile environment?
(Thanks to Mark Eaton of Amnis for introducing me to the concept of Lean a few years ago.)
Red Gate Software’s Dominic Smith mentioned in his presentation at UAEurope conference that the company had found Technical Authors were ideally suited to take on the role of Project Manager for small Agile software development projects. In fact, Red Gate had morphed most of its Technical Authors into to a hybrid Project Manager role.
Dominic made a strong case why Technical Authors made good Agile software project managers:
- They are focused on the user
- They understand the user
- They understand a lot of the technological aspects
- They are used to delivering projects on time
- They are more extravert and people-orientated than programmers (yes, this is broad generalisation)
- They ensure User Assistance isn’t forgotten in the project plan, and that it is considered from the very start
- They can provide a business focus to the project, and are able to kill projects that don’t make business sense any more.
Do you agree?
Disclosure: Red Gate is a client of ours.
Earlier this week, I was asked my opinion on whether a Documentation Manager was needed when the individual Technical Authors are embedded into Agile project teams.
My response was that a Documentation Manager mainly provides people management, project management, process management and content management. If a Technical Author is a member of a software project team, then that team’s Project Manager is probably providing the people management and the project management to the writer.
That leaves the need for someone to manage the processes and manage the content. I suggested managing the content could be done by someone with the role of Editor (or “Content Wrangler”). They might also look after the processes, or they could have another writer take on that responsibility.
It’s then a decision as to whether the organisation sees these roles as senior to the technical writing positions, or as a specialism and consequently on the same job grade.
It does leave the management of the writers’ career progression falling through the cracks, unfortunately.
How do others deal with this issue?
Below is an interview between Ellis Pratt of Cherryleaf and Diana Logan, Documentation Manager at Sage Technologies. In the interview, we discuss Sage Technologies’ new platform for assisting users, the “Sage Ecosystem”, and how user documentation is developed by Diana’s team.
Here are some links to useful information on managing documentation projects:
If you need any advice or assistance in developing user documentation, you should contact Cherryleaf.