Saturday 9 April 2016

What is the Optimal Writer:Developer Ratio?

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:

  1. Are your writers part of the scrum team?
  2. How are you handling peer review?
  3. How much documentation do you need? 
  4. What kinds of documentation are needed?
  5. Who is responsible for bringing together the finished documentation set?
  6. How good is your design team? 
  7. How much technical debt does your product have?
  8. 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.   


  1. Fantastic blog! Do you have any tips and hints for aspiring writers? I’m planning to start my own website soon but I’m a little lost on everything. Would you propose starting with a free platform like WordPress or go for a paid option? There are so many options out there that I’m completely overwhelmed .. Any suggestions? Many thanks! magento developers slc


Note: only a member of this blog may post a comment.