The lovely people at GDS, in association with Write the Docs, put on a great one day mini-conference, Agile the Docs, on 5th December in London. I was asked to present on whether documentation was in the definition of done and I was more than happy to oblige.
Without further ado, here are the slides I used, and here are the notes (I haven't done a lot of editing or formatting on the notes; the links below contain everything I talked about in a more comprehensive - and formatted - way).
If you're interested in learning more about this topic then check out the following articles:
Thank you to Trisha, Rosalie, Jen and Lydia from GDS, and Kristof from Writer the Docs. You organised a short, sharp, interesting conference with interesting and diverse speakers, in a good location, at a sensible time, near a decent pub and a tube station. Top work all round.
On a side note, the BRDC were having a benefit lunch/gala thing in the same conference centre we were, and this was parked outside:
It's an impressive machine in the flesh. And I saw Nigel Mansell in the corridor, which was pretty cool. He looks exactly the same as he did when he won the F1 championship 24 years ago (except for the 'tashe, which went a few years back.). Exactly the same. Either he's aged very well or he looked a lot older than his years when he was an F1 driver.
Anyway, Agile the Docs. Really enjoyed it and looking forward to attending the next one. If you've got questions or thoughts on the presentation use the comments below or tweet me @agiledoc.
If you want to annoy a technical writer, nothing hits the spot quite like hearing "Man, I'm so glad you write the documentation! I know it's got to be done, but boy, it's soooo boring!"
The technical writer-approved responses to this are:
A) smiling through gritted teeth and then seething for the rest of the day,
B) barely-concealed sarcasm about the commentator's level of (il)literacy, or
C) physical violence.
Personally, I veer between B and C depending on the number of witnesses and the size of the person making the comment. (Ok, B. But I spend the rest of the day wishing I knew kung fu and imagining C.) But why, I hear you cry? We ARE grateful for those weird people that sit in the corner and enjoy typing! Seriously, writing documentation sucks!
Oh. Dear. God. *imagines nunchuks*
Right, listen to me. I like writing. I like learning things. I like organising my thoughts on paper. I like helping people. I like helping people by learning about things and then organising my thoughts on paper using the power of writing. This is fun for me, and for my fellow writers. You think I started this blog to make myself rich? Are you kidding me? I write this blog because I LIKE WRITING, and I know a bit about technical writing in an agile environment, and I wanted to help writers in similar situations by sharing my knowledge. You see how that works? I'm helping people by organising my thoughts on things I've learnt and writing it down for other people to read. Just because YOU don't like writing - you big philistine - doesn't mean that everyone else doesn't like writing either. Writing is the mark of an educated civilisation. Writing well is the mark of an educated person. Education is a good thing. You hear me? A GOOD thing.
We don't become technical writers to get rich (damn you, JK Rowling), get famous (hello, Shakespeare) or get people into bed (Lord Shelly, you dog!). Those are benefits for novelists, playwrights and poets, not those of us who help other people work out how to bypass the bad design and hurried implementation of people who are glad they don't have to write the documentation. We live in a gift economy, where the most important thing we have is our knowledge and our skills. Tech writers don't get paid as much as devs, but we're still fortunate enough to do better than a lot of people if we work for any decent company. As such, being able to show people how to do something they couldn't work out for themselves is a valuable commodity because generally speaking tech people don't care for overt shows of material wealth. What gets respect is knowledge and skills, and boy oh boy do your technical writers have those in abundance. You just know too little about what we do to realise that sometimes.
And, while we're on the subject, writing documentation is not dorky, or nerdy, or geeky. Well, not any more than any of the other technical professions we work with day in, day out. For us, writing things, organising concepts, helping people, these are what get us out of bed in the morning and we won't apologise for it. Some people like playing WarHammer, some people take pride on being able to quote every line from every episode of the original Star Trek, and some people are so obsessed about their coffee that they're happy to drink something that's been defecated by an animal. Some people do all of those things. The Venn diagram of these people and people who work in software development contains a lot of overlap, so just remember that next time you think a writer is a bit geeky or weird for not wanting to write code instead of natural language.
Although, to be fair, developers are definitely not alone in their bemusement of why people would want to be technical writers. When someone asks what you do and you say that you're a technical writer, there's often an awkward silence while they try to think of something to say, and that's mainly because the stock answer of "Oh, that's interesting + [question]?" seems to get stuck in their throat. Because not only do they not find technical writing interesting, they find it SO uninteresting that they can't even maintain the social civility of lying. At least with a lawyer or salesman you can make a crack about their lack of morals and know they've heard it a thousand times before, even if you couldn't give a flying duck about the intricacies of their job.
Don't worry, like the weasels in notorious professions, we're also well-used to hearing a stock answer. It's just that for technical writers that stock answer is "Ah.....um.....", and believe me, as people with both morals and a soul that we'd like to keep relatively unsullied, we're much happier with that than poorly-disguised contempt. Still, to help you, here's a few gambits that might help:
- "That's interesting, is your documentation in the definition of done? That's a thorny issue at our place."
- "Yeah, a friend of mine does that too and she loves it!"
- "Man, I couldn't do that job because my English sucks. Much respect to people who've got that talent."
- "Oh, so you teach people about new tech? That's awesome!"
- "Really? Wow, you know I've always thought writers were really sexy....."
Ok, maybe not #5. But the first 4 are all good.
Anyway, having got slightly distracted, back to the issue at hand. I like what I do. Scratch that, I love what I do. Learning stuff, organising that knowledge logically, writing it down for other people - that's like crack cocaine to me. Yes, I do other things like knowledge management and training people because I'm not a pure technical writer any more, and yes, I love those aspects of my job. But my love stems from those core desires that all technical writers have: to learn, to organise, to teach.
That's why people like writing documentation.
This is a tough question to answer. How do you make that assessment? What is the industry standard? What metrics should you track to get empirical evidence?
These questions are particularly apposite if you are requesting more documentation resources, because the person you're asking will - quite legitimately and fairly - want some form of business case involving figures and evidence. But if you've searched for answers to these questions you probably haven't found a lot of concrete information. I've had discussions about the optimal writer:developer ratio lots of times, with lots of people, in both serious budget discussions and informal chats, and with staff at every level from newbie to director. This isn't a topic that never gets mentioned, or an obscure branch of technical writing that only a tiny number of people ever wonder about. It's a question that most Tech Writing/Documentation Managers has either asked or been asked at various times in their careers. It's a live question for a lot of us, today, in the jobs we're in.
But this question seems to be under-represented when it comes to answers, or at least methodologies for finding an answer. Interestingly I found a lot more information when looking for the tester:developer ratio. At least there were a lot more articles discussing the topic. I'd guess there are more blogs by technical writers than by testers, simply because writers tend to like writing, and yet here we are. Perhaps this is something to do with the difficulty of quantifying documentation? It seems like this is one of those questions that has people going round in circles and so they just stop thinking about it and accept whatever ratio they're given before they go mad.
When I sat down to write about whether documentation should be in the definition of done, I found a similar situation. There was a lot more discussion of the topic, but no-one had a real answer, or a good way of getting there. Generally everyone pounded on each other's ideas because "my scenario is different so that won't work for me" and "there is no answer, it's all contextual, here's a context where your idea won't work". This continued until people got bored and stopped posting on that thread. So I went down the road of "what are the questions you need to have answers to before you can decide if documentation should be in the DoD", and that approach seemed quite useful to some people.
Let's follow a similar approach here and ask: What information do you need to know before you can decide how many writers you need? Note that there is a re-framing of the question here, from a question about a ratio to a question about a number. This is because I work in agile environments and that changes the nature of production from one where you have X developers, Y testers and Z writers in a large pool to one where you have small teams that each have x developers, y testers and z writers. Therefore it doesn't necessarily make sense to focus specifically on the writer:developer ratio, but it does make sense to focus on the number of writers needed in each agile team, and then use this to get a total number. Also, when you talk of an "optimal ratio of writers to developers", what defines optimal? You have to have something against which to judge "optimal", and these questions should help you figure that out.
Before we go on:
- Because it's more of a general resource planning and managerial standard, I'm assuming you've already taken into account the need for cross-training and knowledge transfer to prevent single points of failure, the expectation that you need holiday or illness cover, and generally are aware of the need for slack/contingency in the system.
- Regular readers will know that I consider multi-functional teams to be a unicorn - very desirable and very rare to the point of being largely mythical - because it is very difficult to be professionally competent at even 2 of the roles you need to produce good software, let alone more than 2. Therefore I have no truck with commentators who suggest that there "is no separation between content developer and software developer". Not to gild the lily of my previous arguments on this point, but if your developers are Richard Stallman, Linus Torvalds and Vint Cerf then a) why the hell are they spending their time producing end-user documentation, and b) any professional writer will be able to write better documentation than any of them. Let's not pretend that a multi-functional team of very technical non-writers will produce good documentation. They won't.
Right, the questions:
- Are your writers part of the scrum team?
- How are you handling peer review?
- How much documentation do you need?
- What kinds of documentation are needed?
- Who is responsible for bringing together the finished documentation set?
- How good is your design team?
- How much technical debt does your product have?
- What SHOULD your writers be doing, vs what ARE they doing?
1 - Are your writers part of the scrum team?
If they are, they shouldn't commit to a sprint if they can't document it. If the writer or writers in the team are a bottleneck that cause the other team members to commit to less than they can do (because the team can only go as fast as it's slowest member), then you need another writer on that team. This does make the assumption that it is sensible for documentation to be in the definition of done, so make sure that the problem is a lack of resources rather than a situation where there's too much documentation to be done in the last couple of days of the sprint. If your writer has very little to do in the first half of the sprint, that's not a resource problem, that's an organisational problem.
If your writers aren't part of the scrum team - e.g. they work a sprint in arrears - they should still be committing to the sprint when the team does, even if they won't document it until the next sprint.
2 - How are you handling peer review?
Do the writers have to build in time for peer reviewing each other's work into their willingness to commit to a sprint? If so, do developers and testers have to do similarly for the work of their peers? If it's only the writers who have to do this, there is an additional overhead that will cause them to be able to do less writing, which means it is more likely they'll become a bottleneck for the rest of the team.
3 - How much documentation do you need?
This isn't about types of documentation, which is covered in the next point, but simply about the volume. For Clash of Clans the documentation required is minimal, no matter how many developers you have. But for Microsoft Excel the documentation required is huge. 1000 developers working on a black box that takes in one value and spits out another might only need 1 writer. 10 developers writing a complex, parameter-heavy application with multiple APIs, web services and SDK hooks might need several writers. (This is the main reason why there is no point suggesting a generic writer:developer ratio.)
4 - What kinds of documentation are needed?
Unlike the volume question, this is about different types of technical documentation. If you have multiple specialist documentation needs, e.g. API, SDK, end user, configuration, specification, FAQs, raw HTML/CSS web pages, sales engineering, technical marketing, etc, then you'll need more than one writer, even if some writers are not team-specific (e.g. the SDK writer may work outside of the scrum teams). Ultimately, you need to document all of the tasks that a user could perform, and you need those tasks documented by people who understand what information different users will need (e.g. a data entry end user needs to know very different things to a developer end user who want to use your API).
5 - Who is responsible for bringing together the finished documentation set?
This is for situations where multiple teams feed into the same product (or product set). Do your writers just write, or do they design documentation, mock-up screenshots or wire frames, deal with translators or printers, manage other writers, and so on? If any or all of the writers have responsibilities that go over and above writing documentation then you should consider hiring an editor, principal writer, documentation manager, translation manager, or other specialists who can manage these complex issues with a view over all the documentation and products. As a side note, this should have a decent ROI because a specialist will be more efficient and more capable of achieving economies of scale across all documentation sets. They'll also free up the writers to do what they do best: writing.
6 - How good is your product design?
Good design should eliminate a lot of the need for writers, because the design makes the software intuitive to use. For those of you that have used both products, think of the difference between the TFS and JIRA work item tracking applications. TFS has been designed from the ground up to be easy to use and to be fully integrated into the .NET framework and IDE, as well as being "Agile-native". This makes it intuitive to use, and as such the documentation can primarily focus on SDK and API integration, rather than end-user documentation. JIRA has grown organically from a defect tracking system and has had various elements bolted on in response to market needs. This makes it difficult to use, and the end-user documentation is accordingly much greater. I'm not suggesting that all Microsoft products are this intuitive (SharePoint being a great example of something that's really not), nor suggesting that all Atlassian products are difficult to use (Confluence is the most user-friendly collaboration tool around), just that TFS and JIRA demonstrate how 2 different applications that do roughly the same thing can be miles apart in usability and therefore documentation requirements.
7 - How much technical debt does your product have?
I've said before that documentation shouldn't be used to cover technical debt, but let's be honest: it often is. If your product has a lot of technical debt this will make the documentation that much more complicated and voluminous, which will mean that you may need additional writing resources to compensate.
8 - What SHOULD your writers be doing, vs what ARE they doing?
Start with a list of the thing your writers currently do, then write a "dream list" of everything you think they should be doing instead of/as well as what they're doing now. Write down everything you can think of. Then scrunch that list up and throw it away because it's madly unrealistic (but it's good to get it out of your system), and write another list of what could be achieved if you had additional writers. Focus on improving efficiency and customer satisfaction, and decreasing support costs. This is ROI 101 and you want to focus on selling the idea of increasing sales and decreasing support costs. There's no point trying to sell an "optimal writer:developer ratio" because a) that's not going to get anyone motivated to support you, and b) there is no such thing as an optimal writer:developer ratio, which is one of the reasons you're reading this.
When you've got answers to all of these questions you should have a better idea of, and better evidence for, the number of writers you need in each scrum team. Add those numbers up, and that's your overall answer.
From the Agile Manifesto:
"The most efficient and effective method of conveying information to and within a development team is face-to-face conversation."
There are times when you can't be in the same room as some or all of the rest of your team to have that face-to-face conversation, so how can a writer work as part of a team remotely?
Let's get one thing clear: Agile can and does work with remote team members. This applies to writers as much as developers, testers, designers, etc. In theory even a scrum master could be remote (although that might be one of those times when theory and practise diverge). I'll explain how this can work, but nothing beats practical experience and as a manager of writers I've managed all 4 of the possible scenarios:
- Local writers working with local teams;
- Local writers working with remote teams;
- Remote writers working with local teams;
- Remote writers working with remote teams (i.e. a worker who is not working in the same geographical location as me and nor are they working in the same location as their scrum team, who were based in a different geographical location to mine).
I know that all of these scenarios can work for writers, because I've managed writers who have been successful and productive members of scrum teams in all of these scenarios. There's no doubt in my mind that the simplest and most effective situation is for all team members to be in the same location, and preferably the same office space***. But there are often good reasons why one or more members of a team will be working remotely, and, if you are the remote worker, it is your responsibility to find ways to be an effective member of the team. It is the responsibility of the rest of the team to help you be effective.
The following lays out the most important things for being an effective remote worker in a scrum team over a period of time:
1 - Communication
2 - Trust
3 - Availability
4 - Clarity of goals
Before we look at these in more detail, it's worth emphasising that if you haven't worked with all of the remote team members before, then face-to-face meeting at the start of the process can be very helpful. Putting a face to an email signature and having an idea of them as a living, breathing person can make faceless communication much less fraught. It’s very easy to read the wrong intentions into written communication, especially if you don’t share a common native language and/or culture. Meeting people can prevent a lot of that kind of problem by giving you a sense of who they are as people - remember that most communication is non-verbal, so you'll get far more out of a 30 minute meet-and-greet than you will out of a month's worth of dialling in to conference calls.
If meeting the team in person isn't possible for whatever reason, try doing virtual face-to-face meetings using video conferencing. Introduce yourself, ask questions about what each team member does, what they need from you and what you need from them. This will at least give you some kind of baseline to work from, because you don't want your first person-to-person contact with a team member to be at a moment of stress or pressure.
Assuming you've met your team either in person or by video, lets look at the 4 key areas in more detail.
Communication
Clear, agreed lines of communication are key when working in an scrum team. By working remotely you're giving up one of the biggest assets that a scrum team has - regular face-to-face communication within the team - and as such you must agree on methods and systems for replicating this as much as possible. The obvious tool is video conferencing, and it should be a matter of course that you attend all ceremonies using this tool. But over and above these set-piece meetings, use instant messenger, email, Slack, Hangouts, or whatever combination of tools that works for you and your fellow team members, and use them a lot. Part of being a remote worker is making sure that your team remembers and includes you, and if you've never worked remotely before you might be surprised by how easy it can be to feel, or be, forgotten. Regular (at least daily) contact with your team outside of the set-piece ceremonies will help you keep in the loop, and help your team mates keep you in the loop, and nothing is more important for an agile team than everyone knowing what is going on.
Trust
My experience of managing writers is that a good member of staff is good regardless of whether they are working remotely. I appreciate staff who are pro-active, good at gathering information, independent and who know when they need to involve me and when they don't, and that is the same for both local and remote workers. Unsurprisingly, these skills are also key to being an effective member of a scrum team, especially if you work remotely and you don't have a long history with your team. You can't assume that your new team will have an immediate level of trust in you and your work, because until you've proven it - and they've proven the same to you - you're all still finding your way.
It's only once the team's velocity has stabilised that the team as a whole will have a good feeling for which team members have what strengths and weaknesses. The developer who's not the quickest at getting their task done, but who is the social glue that holds the team together, provides a value over and above just their output; as a remote worker, you don't have this kind of opportunity to provide additional value because you're not in the office with the rest of the team. Therefore your team mates need to trust the quality and quantity of your output, and your contributions to meetings - those are your core competencies and you will be judged on them. That can feel a bit harsh sometimes, but one of the downsides of remote working is that your lack of physical presence gives the rest of the team less day-to-day evidence on which to evaluate your contribution, so make your contributions regular and high-quality!
Availability
If there is a particularly annoying problem when dealing with remote workers, it's that they aren't working when you are, so you can't get hold of them. This is really, really irritating because they have become an impediment to your work, and as they are part of the same scrum team that should not be happening, even if they are part-time or working in a different time zone.
To be clear, I'm not saying that people who work part-time or in a different time zone are a impediment to the team. What I am saying is that the team should know when someone will be available so they can plan accordingly. If I need something from a part-timer who works 10am - 2pm 5 days a week, then I can just ask them on any given day during that time slot. That's not an impediment because I know when they will be available. Similarly, if I work 9am - 5pm and a remote worker in a different time zone works the equivalent of 11am - 7pm, that's also not an impediment because I know I can contact them between 11am and 5pm. The impediment is the uncertainty of when I can and can't get hold of a team member.
To remove this impediment, try instigating a block of core hours – e.g. 11am – 2pm - when people will always be available for ceremonies, conference calls, IM/email exchanges, etc. This gives everyone the flexibility at the beginning and end of the day when you aren’t expected to answer immediately, whilst still providing a standard block of time each day to ask questions, get answers, have meetings, etc. This will help with planning and time management, and remove the impediment of uncertainty.
An additional remedy is making sure all calendars are shared, either by sharing individual calendars or, preferably, having a team calendar where everyone adds in their holidays, booked meetings, and so on. This provides a central location for remote and local workers to easily find out when a person they need will next be available.
Clarity of goals
There are short term and long term goals that the whole team should be working towards. The short term goals will normally be sprint and release based, so it is important to clarify up front what deliverables are included in the Definition of Done for both the sprints and the release. This is even more important if you're working remotely because the assumption for a remote worker is that they tend to be slightly more autonomous, especially if they are a contractor and/or non-developer.
For the long term, try to build a common goal and sense of direction between both teams. Meeting face-to-face helps build the required trust to work as a team; having a shared, agreed goal helps that team have a focus. In general terms, it’s about developing strong relationships quickly and making sure you’re all pointing in the same direction. Again, as a remote worker this is particularly important.
What else do you think is important when you're providing documentation remotely for a scrum team? Sound off in the comments!
Update: Content curator, blogger, entrepreneur and all-round high-achiever Belle Beth Cooper has put together a stupidly good guide to remote working which I can't recommend highly enough. If you want more articles, Belle has kindly added a section at the end of the guide with her recommendations.
*** - The caveat is that some people prefer to be on their own for periods of time, and
suitable allowances such as private offices (where available) should be
made for that, but they should still be easily reachable.
"Technical debt" is a concept in programming that describes all of the work that has to be done later because it wasn't done (or done right) at the time. Wikipedia sums it up nicely:
"The debt can be thought of as work that needs to be done before a particular job can be considered complete. If the debt is not repaid, then it will keep on accumulating interest, making it hard to implement changes later on. Unaddressed technical debt increases software entropy [software complexity]."
A solid overview of technical debt in software projects can be found here. That link details the technical debt experienced within the code line, which is the common understanding of where such debt accumulates.
However, the following issues are also a form of technical debt for your documentation:
- A backlog of documentation tasks (where documentation is not in your definition of done).
- Known errors in your documentation.
- Known omissions in your documentation.
- Known ambiguities in your documentation.
- An out-of-date Table of Contents or index.
- A lack of consistent terminology and/or use of standards within a document.
- A lack of consistent terminology and/or use of standards within a documentation suite.
- A lack of consistent terminology and/or use of standards across different documentation suites.
- Documentation that is out of sync with the most recent release.
- Missing documentation (e.g. you have installation notes but no configuration guide).
- Multiple documents that could (and therefore should) be single sourced.
There are other types of technical debt for documentation; these points should be thought of as examples, rather than as an exhaustive list. As all technical debt is shared by the whole team, our debt is their debt and vice versa. I'm sure you can imagine that there is some contention about whether documentation is included in the "official" definition of technical debt, but that largely boils down to whether or not documentation is included in the Definition of Done, which I've discussed elsewhere.
The important point is that, like a software application, a large piece of documentation can be very complex, and the more errors or omissions there are, and the earlier these occur, the more you pay for them when trying to fix the errors or include the omissions at a later date. There is no magic bullet for fixing technical debt, so I won't try to provide one here, but at a later date I will be posting about the value of documentation, and hopefully that will give you some ideas about how to persuade people of the importance of getting your documentation correct, consistent and complete.
That aside, don't be afraid to talk in terms of technical debt if you need to persuade your Product Owner to prioritise tasks that will fix these problems. The more that your documentation issues are seen as being similar in scope and type to the software issues, the more likely you are to be supported when you ask for a higher priority to fix your technical debt. It's important to frame requests in language that your development-oriented team mates can understand, and most developers understand both the importance of minimising technical debt, and the frustration that having it causes.
When we talked about whether documentation should be in the Definition of Done, there were 6 factors that spoke directly to the answer for teams that weren't multi-functional (which is the vast majority of teams that practise scrum). That article focused on what combination of those factors would allow you to add documentation to the Definition of Done (DoD); this article looks at those factors in a bit more depth and explains why they are so important.
Let's remind ourselves of the factors which need to be looked at:
1 - Can anyone other than the designated writer(s) complete the documentation tasks?
2 - What proportion of documentation can be done quickly by the writer, e.g documenting a bug (as opposed to complicated enhancements, for example)?
3 - Is the quality of the input to the documentation tasks reliably high and consistent?
4 - Is the number of deliverables less than 2 (or if 2 or more, can they be single-sourced)?
5 - Are there proscriptive standards and templates for the documentation that is being produced?
6 - Are complicated enhancements front-loaded by the team to allow the writer to work on them as soon as possible?
Don't forget that for single- or semi-functional teams the question of whether documentation is part of the sprint deliverables is not a factor; this is about whether you can deliver documentation at the end of each sprint, and if you can't then you (or rather your company) shouldn't commit to providing documentation as a sprint deliverable.
1 - Can anyone other than the designated writer(s) complete the documentation tasks?
The answer to this question determines - for the specific purpose of working out if documentation should be in the DoD - whether the team is single-functional or semi-functional. If there are, for example, 6 developers, 2 testers and 1 writer, and only the writer can produce documentation, the team is single-functional. If one or more developers or testers can produce documentation to the same standard as the designated writer then the team is semi-functional. Note that adding another specialist writer to the team won't make the team semi-functional, because documentation can't complete until testing completes, so although this will provide more manpower to get the documentation done, it won't change the inherent problem that non-multi-functional teams face - the need to work in a linear process within each sprint. If one or more developers or testers can produce documentation, they are able to take on the documentation tasks as well as tasks in their own speciality earlier in the sprint. This is what makes the team internally agile. The more developers and testers that can produce documentation to the correct standard, the closer the team is to being multi-functional (for the purposes of providing documentation).
2 - What proportion of documentation can be done quickly by the writer, e.g documenting a bug (as opposed to complicated enhancements, for example)?
This is the key metric that determines how much work the writer can do before testing have completed their tests, and how much will have to be done after testing have completed. The development team should provide information for each bug in the form of "This is what was happening", "This is why it was a problem", "This is what happens now". Once the developer has done this work and sent it for testing, it is rare for this information to change (i.e. testing might find an issue with the developer’s fix, but the "This is what happens now" information rarely changes), so the writer can document a bug before it's been tested and move on with a low chance of rework later on. However, if a writer is working on enhancements, especially UI changes, then there is a much higher chance that any issues found in testing will affect the documentation, therefore the chance of rework is much higher, therefore the chance of the writer completing their tasks before the end of the sprint is much lower. For a single-functional team this proportion needs to be very high to allow documentation to be part of the DoD, otherwise documentation will be a likely point of failure when determining if a sprint completed successfully.
One thing to bear in mind: Because of the inherent fluidity of new work and the fact that a large piece of development might be done over more than one sprint, and it is easier to document it as a whole once it’s completed (so you can fully understand it, take screen shots, work on it as one piece of work rather than task-switching all the time, etc), this factor is something to think long and hard about. If you have a lot of enhancements to document, especially ones that tie together to make a few large enhancements, you really should opt for documenting outside of the sprint cycle, no matter what your answers are to the other factors.
If documentation IS part of your DoD, you’ll be at the end of the accordion, and if development or testing don’t hit their deadlines within the sprint then the writer will get squeezed and squeezed until either quality or completion - or both - become an elusive dream. And if development and testing DO hit their deadlines then they’re twiddling their thumbs for several days while you write the documentation. It’s an intractable problem that is best solved by removing documentation from the DoD and working in sprint bundles to make development and testing more efficient, and to minimize rework for the writer, but if documentation is part of the sprint deliverable then it's something that has to be managed as much as possible.
3 - Is the quality of the input to the documentation tasks reliably high and consistent?
By "high" we mean "All the information that the writer needs to document as much of the work as is possible before development and testing have completed, for example, wire frames showing the expected field positions, a complete explanation of the functionality and what it will be used for, a complete listing of all parameters that affect the new work or are affected by it, and any other information that the writer needs to provide to the customers."
By "consistent" we mean "Every work item that is in the sprint has this information in it, every time, without fail."
If the quality of the input is not both of these things then the writer will have to spend a lot more time finding the information out, which can only be done after testing have completed, and again, the writer is much more likely to fail to complete their tasks by the end of the sprint. It's also much more inefficient in general terms; the information is all there, but the writer will have to get it manually from developers, designers, the Product Owner, etc, so this is good practise anyway.
4 - Is the number of deliverable less than 2 (or if 2 or more, can they be single-sourced)?
Deliverables might mean traditional documents such as help files and release notes, but equally it could be editing help messages and other on-screen text, writing API documentation, and so on. The point of concern here is two-fold: Firstly, will the writer have to enter the same information in more than one deliverable in any given work item (unless it can be single-sourced, in which case the practical answer is "No") and secondly, Will the writer have to complete (format and prepare for release) more than 1 deliverable at the end of the sprint? If the answer to either of these is Yes, then the writer has to either add the same information into multiple deliverables, or different information into different deliverables. Either way, there is an overhead in these scenarios that adds more required time onto the documentation.
5 - Are there proscriptive standards and templates for the documentation that is being produced?
What is one of the most difficult and time-consuming things for most people to do? Making a decision. What is a guaranteed way to ensure inconsistent and therefore poor quality documentation? Letting people make individual decisions about formatting, language, and so on. Having incomplete - or missing - proscriptive standards and templates therefore both costs more time AND lowers quality. Even if a writer is good at making consistent decisions, there is still the possibility - the probability, in fact - of errors or inconsistencies being made from time to time, and as the decisions will have to be made every time they work on a documentation task there is an in-built bottleneck and inefficiency there. Anything which prevents the writer from writing should be seen as an impediment by the Scrum Master and as waste (in LEAN terminology) by the company. So perhaps a more apt question would be: Why WOULDN'T you have proscriptive standards and templates?
6 - Are complicated enhancements front-loaded by the team to allow the writer to work on them as soon as possible?
Because documentation can't complete until testing completes and because, as noted in #2 above, there is a much higher chance of rework with an enhancement, any enhancements that require significant documentation should be front-loaded by the developers if possible. This is not always possible, because development need to start getting work to testing, and complicated enhancements often take longer to do than bugs, so bugs get done first to ensure that testing have work to do as soon as possible in the sprint. Bugs can also be "quick wins" for development. There is an inherent tension here, because bugs can be normally be documented quickly (especially if the quality of the input is high and consistent and you have proscriptive standards) and also can be estimated more easily. If you have 10 bugs left, for example, you will know that all things being equal it will take you 2.5 hours to document them (or whatever your rule to thumb tells you - mine says 15 minutes per bug as an average). But if you have 10 enhancements, all with a different number of story points then you can still estimate them, but it's something you have to work out as opposed to being something you know. I know that 15 minutes is enough time on average to document a single bug because over many years of experience 15 minutes has proven to be a reliable estimate for me in many different situations. But I can only estimate how long it will take me to document an enhancement. That estimation may be more accurate as I learn the product and participate in the grooming to properly understand the work that will be done, but I will never have the level of confidence in it that I do with my bug estimates. The larger and/or more complex the enhancement, the less accurate your estimate will be. And as development for a single-functional team is linear (i.e. each sprint follows a Waterfall pattern) and documentation comes at the end, it's much easier to tell if you will complete on time if you only have bugs left to document. The more enhancements that are left until the end of the sprint to document, the greater the chance of you failing to complete your documentation tasks and being the point of failure. This is doubly annoying because it looks like the writer has failed, but actually it's the system that has allowed the whole team to fail by not understanding what each function within the team needs, and when they need it.
Once you've understood these factors you can use them to help make your decision on whether documentation should be in the DoD. Good luck!
Welcome to the thorniest, most contentious question is the world of agile documentation.
If you've discussed this with many people, you'll have probably heard views that range from "Who cares?" (thank you cynical developer-types) to "It ABSOLUTELY MUST/MUST NOT be in the Definition of Done!! Anything else is madness!!!" (thank you dogmatic autodidacts) and everything in between (thank you normal people).
So let's get one things clear from the outset: There is no objectively-right-in-every-situation answer to this, only an answer which is right for your situation.
This is why you will hear such a broad and contradictory range of opinions on the subject. That's not to say that some of those opinions aren't correct for your situation, but what works in one scrum team situation might not work in another, even within the same department, let alone the same division or the same company.
There's a good reason that there is no one-size-fits-all answer, and it's entirely to do with the unicorn at the heart of scrum. Truly multi-functional teams are like unicorns - very desirable and yet seemingly a myth - and as such it isn't possible for most team members to pick up any given task. Teams range from the entirely "single-functional", where a developer can only develop, a tester can only test and a writer can only write, through "semi-functional", where, for example, some developers and writers can also test, some testers and developers can also write and some testers and writers can also develop, up to truly multi-functional, where any member of the team can pick up any task.
For a truly multi-functional team, the decision on whether documentation should be in the Definition of Done (DoD) is based simply on whether documentation is part of the deliverable due at the end of each sprint. If it is, then it's just another task and documentation is in the DoD, if it isn't part of the deliverable then it isn't in the DoD***.
Outside of truly multi-functional teams though, there are several factors that need to be taken into account:
1 - Can anyone other than the designated writer(s) complete the documentation tasks?
2 - What proportion of documentation can be done quickly by the writer, e.g documenting a bug (as opposed to complicated enhancements, for example)?
3 - Is the quality of the input to the documentation tasks reliably high and consistent?
4 - Is the number of deliverables less than 2 (or if 2 or more, can they be single-sourced)?
5 - Are there proscriptive standards and templates for the documentation that is being produced?
6 - Are complicated enhancements front-loaded by the team to allow the writer to work on them as soon as possible?
(See here for a more in-depth discussion of why these things are required if you're not sure.)
For the purposes of this discussion:
If #1 is a NO, then the team is a "single-functional" team.
If #1 is a YES, then the team is a "semi-functional" team.
For a single-functional team:
If #2 < 75% then documentation should not be in the DoD.
If #2 = 75% - 85% then documentation should only be in the DoD if #3 - #6 all = YES.
If #2 >= 86% then documentation should only be in the DoD if at least 3 out of #3 - #6 = YES.
For a semi-functional team:
If #2 =< 50% then documentation should not be in the DoD.
If #2 =< 75% then documentation should only be in the DoD if #3 - #6 all = YES.
If #2 >= 76% then documentation should only be in the DoD if at least 3 out of #3 - #6 = Yes
If you can't answer YES to at least 3 out of #3 - #6, then for a single- or semi-functional team documentation should not be in the DoD, no matter what the answer to #2 is. This is because those 4 questions determine whether your processes and standards will provide enough support to the writer to allow them to get the documentation done without a significant lag at the end of sprint. If less than 3 are YES, then there are too many possible problems for the writer(s) to overcome. (There's
no absolute guarantee that a writer will face problems, but in the
real-world situations to which this applies you shouldn't assume
everything will be smooth sailing all the way - that's just
unrealistic.)
A note about the numbers: No sprint should be more than 80% full, to allow for contingency. If #2 <= 85% for single-functional teams or <= 75% for semi-functional teams, then you are getting too close to using up all of your writing contingency by asking the writers to work on complicated work items that are likely to take longer, and have a higher expectation of rework if the writers works on them before testing has completed. These figures are therefore partly a matter of logic and partly a matter of realism. In the spirit of scrum, you should adjust them based on your own experience within a mature sprint team with a settled velocity.
You may have noticed that for both single- and semi-functional teams I have nowhere mentioned whether documentation is part of the sprint deliverable. If you did notice, well done and gold star to you! This is a key point: If your team does not have the skills, processes and standards in place to allow documentation to be completed in-sprint, then it should not be part of the sprint deliverable. This is an issue that should be decided before agreeing a contract with a client.
In summary, development is a process and some things simply have to be done in order. Agile helps with that, but, unless you have a truly multi-functional team, it doesn’t change it. Therefore, it's fair to say that to the question of whether documentation should be in the DoD, there isn’t a right answer, just answers that have varying degrees of usefulness for your situation. Hopefully the factors listed above will help you make that decision.
*** - There are other good reasons why documentation might or might not be in the DoD in this circumstance - every team, product and company is different, after all - but in principle this is the sole reason, and there's no need to muddy the waters by talking about the possible differences in business process or contractual obligations.
