Saturday 30 April 2016

In Defence of Documentation

In the past I've written about the benefits of documentation, and documentation ROI, and how some people see documentation as a cost rather than a value, and various other short form essays on documentation issues.  But none of these really get to the heart of what I want to say about documentation, they just skirt the outright point.

I want to defend documentation, both as a profession and as a business necessity.

More than that, I want to go on the attack, to shout loudly and widely that what we do is important and valuable and good, that without documentation your knowledge is entirely transient and dependent solely on your ability to keep your staff working for your company, because everything that customers need to know is locked in your peoples' heads.  I want to corner you and force you to acknowledge that there is no information about your products that shouldn't be written down in a clear and consistent manner, that customers are always better off with great documentation, that there is no area of your business that couldn't lower costs and increase efficiency with just a little sensible documentation of the things that are important.

I watch and I grieve as companies choose to value only those things they can easily measure, whilst doing everything they can to reduce those things which have a value that can't be entered as a number in a spreadsheet.  But of course, strategic thinking, or planning, or playing golf with a customer, these are not activities with a measurable value.  But they are in the MBA play book, and the Sales handbook, and, dammit, everyone knows the value of these things, right?

It is odd how these activities, which so many companies put great store in, are never the activities that are cut during the hard times.  No, it's things like documentation, concrete deliverables that add real value for the customer base, that are cut.  Not enough lines on the spreadsheet, you see.  Besides, what's important is sales, and they sell dreams and visions.  How does your documentation help them sell?  No, no, no, far too prosaic.  No-one dreams about having great documentation!  People want to believe in our products!  So we take them onto the golf course and spin our tales of efficiency savings and cost cutting and the awards they could win for their implementation, and whilst they're misty eyed about their future prospects we shake their hand and tell the guys back at the office to fax the paperwork over ASAP.  What's that?  We don't have enough people to implement or support it?  We've sold something that hasn't technically been developed yet?  Oh well, don't worry, that's for the business to sort out.  Now get a move on, we've got dinner with another potential client tonight!

This short term, pipeline-obsessed mentality is absolutely fine within the sales team, because that's their job.  But a sales mentality is a world away from what real leadership of a company looks like.

Leadership looks at much more than the numbers in a spreadsheet.  Leadership sees the intangibles like quality, integrity, reputation.  It sees the long term benefits of investing in the undersold professions that provide the difference between middling and market leader.  It disrupts not through marketing campaigns but through old-fashioned concepts like "investing in staff", "trusting specialists" and "research".  Great ideas that don't come from the leadership are treated as things to be encouraged for the benefit of the company, not strangled at birth in case they threaten the comfy chairs. 

These leaders spend money on the boring things like documentation, QA and testing, things that don't have a simple relationship to the balance sheet.  Why?  Because they know that a company that makes products that are unreliable, user-unfriendly and poorly documented will only sell to the ever decreasing market of those people who haven't been disappointed by said company before.  And meanwhile the company will have to throw more and more money at salespeople and marketing experts to make up for the deficit in confidence that customers have in the products being pushed at them.

What technical writers do is not cool.  It's not hip, trendy, sexy, or chic.  It's far more valuable than any of those things: It's important.

If you don't get that, why would a technical writer want to work for you?

I'm lucky that I work in a place that values what I do, but I see too many of my documentation peers broken on a poorly-resourced wheel of disrespect. For those of you that don't feel valued?  Leave.  You and your skills are worth more than that.

Measuring Technical Documentation

A list of things you can measure about technical documentation.

When measuring these things, you need to find your baseline figure - what the figure is now - and aim for each figure to go up (e.g. documentation coverage) or down (e.g. number of bugs) over time.  This can be measured on any timescale you want, but probably the most useful would be one of monthly, yearly, by sprint, or by release.

This list is not intended to be exhaustive or authoritative (inspect and adapt!). Not all of these measurements will be relevant to every situation. How you measure these things is not covered here. There are other measurements you can perform for writing teams or individual writers; these are not included here.

The terminology should be understood as follows:

 - A documentation set is a vertical slice, i.e. the documents that cover a complete product.
 - A documentation type is a horizontal slice, i.e. a type of document that will be in most if not all documentation sets, such as a help file, configuration guide, etc.


  • All documentation sets are complete, i.e. contain every required documentation type;
  • All document types are complete, i.e. contain every required section.


  • Every product has a documentation set;
  • Every documentation set covers all aspects of the product;
  • Every document type that is relevant to the product is included in the documentation set;
  • Each document covers every aspect that a user would find in a default installation.
  1. Coverage doesn't have to include ALL documentation for a product, as some documentation - e.g. training material, sales and marketing literature - does not come under the heading of technical documentation.  Where this boundary lies is a question for your company to answer.


  • Every document set contains the same document types (if needed for the product that the documentation set covers);
  • Every document type follows the same formatting and layout guidelines;
  • Every document follows the same formatting and layout guidelines;
  • A global glossary defining all terms is available and complete;
  • Style guidelines defining writing style are available and complete;
  • Every document uses the same terms in the same way, i.e. adheres to the global glossary;
  • Every document is written in the same style, i.e. adheres to the style guidelines;
  • Every document is clearly labelled with related release(s), product(s) and version.
  1. Where there are multiple delivery mediums, the formatting and layout guidelines should provide the same look and feel as much as possible.
  2. There may be multiple glossaries for different markets, e.g. English vs American English, or different industries where standard terms are different.


  • The total number of reported documentation bugs;
  • The number of reported bugs per documentation set;
  • The number of reported bugs per document type;
  • The number of reported bugs per document;
  • The average time to correct any documentation bug;
  • The average time to correct bugs per documentation set;
  • The average time to correct bugs per document type;
  • The average time to correct bugs per document.
  1. "Average time" means "from the time the bug is accepted onto the backlog to the time the fix has passed testing".  This can be measured in days, sprints or releases.


  • The percentage of total documentation (%oD) that has been peer-reviewed;
  • The %oD per documentation set that has been peer-reviewed;
  • The %oD per document type that has been peer-reviewed;
  • The %oD per release that has been peer-reviewed;
  • The %oD that has been reviewed by technical staff;
  • The %oD per documentation set that has been reviewed by technical staff;
  • The %oD per document type that has been reviewed by technical staff;
  • The %oD per release that has been reviewed by technical staff;
  • The %oD that has been reviewed by customer-facing staff;
  • The %oD per documentation set that has been reviewed by customer-facing staff;
  • The %oD per document type that has been reviewed by customer-facing staff;
  • The %oD per release that has been reviewed by customer-facing staff.


  1. "Peer reviewed" means other professional technical communicators - writers, editors, documentation managers.  They will check for technical communication errors/issues/omissions.
  2. "Technical staff" means architects, designers, developers, testers.  They will check for technical errors/issues/omissions.
  3. "Customer-facing staff" - means those staff who install, configure and support the product for the customers. They will check for understandability, ambiguity, and clarity both for themselves and on behalf of the customers.


  • All documentation is written using a recognised Help Authoring Tool, e.g. MadCap Flare, Adobe FrameMaker, and/or a recognised technical communication methodology, e.g. topic-based authoring, DITA;
  • Different versions of documentations, e.g. for different markets or industries, are created from base versions;
  • Standardised templates are used when creating new pages or new documents;
  • All in-progress documentation is stored in a versioned repository, e.g. TFS , GitHub, alongside the release branch it relates to;
  • All released documentation is stored in a backed-up documentation management tool, e.g. SharePoint, Documentum

Technical Debt:

  • The total number of known technical debt issues across all documentation;
  • The number of known technical debt issues per documentation set;
  • The number of known technical debt issues per document type;
  • The number of known technical debt issues per document;
  • The average time to correct any documentation technical debt;
  • The average time to correct technical debt per documentation set;
  • The average time to correct technical debt per document type;
  • The average time to correct technical debt per document.


  1. "Average time" means "from the time the debt is accepted onto the backlog to the time the debt has been paid".  This can be measured in days, months, sprints or releases.


  • All documentation (including the glossary) is available for viewing and/or download on a public website (this may be limited to customers only);
  • All documentation (including the glossary and style guidelines) is available for viewing and/or download on an internal intranet/portal/document management system;
  • All web-based documentation adheres to W3C accessibility guidelines;
  • All documentation relating to servers is available in simple formats such as RTF or HTML/XML/XHTML (because a lot of servers won't have Office or a PDF reader installed).

Bug reporting:

  • Documentation bugs are reported in the same way and in the same system as software bugs;
  • Documentation bugs are added to the backlog in the same way as software bugs;
  • Documentation bugs are given the same type of weighting and value as software bugs.

Customer feedback:

  • External customer feedback is requested after every release (potentially every major release if you're releasing incrementally);
  • Internal customer feedback is requested after every release (potentially every major release if you're releasing incrementally);
  • Negative/constructive feedback is treated as a bug;
  • Negative/constructive feedback is treated as more important than what is "right", e.g. if there is multiple feedback suggesting that more screen shots are needed, this overrides the standards that say screen shots should be kept to a minimum;
  • Negative/constructive feedback is treated as more important that a writer's sense of pride.

Customer feedback suggests that:

  • Every documentation set is useful;
  • Every documentation type is useful;
  • Every document is useful;
  • Every documentation set is accurate;
  • Every documentation type is accurate;
  • Every document is accurate;
  • Every documentation set is delivered in a timely fashion;
  • Every documentation type is delivered in a timely fashion;
  • Every document is delivered in a timely fashion.


  1. "Timely fashion" may mean before delivery of the software, or at the same time as the software.  This is dependent on the customer needs, i.e. internal customers will often want all the documentation before the software is released to customers, and customers may want the release notes before the software is delivered, but not need the help file until they receive the software.

Any suggestions for omissions from this list are welcome.

Wednesday 27 April 2016

Got too much on your plate?

It's Monday/Tuesday/Wednesday/Thursday/Friday morning, your desk is full of crap, your inbox has 326 unread messages, you've got 31 Yammer notifications, 8 uread private Slack messages, your calendar has at least 4 meetings in it every day this week, with more to be added, and everyone wants things from you now. Or preferably earlier than that. Oh, and you've got your own work to do. Still, this is the way work is...

Or is it? Because you know there are other ways, right?

But that's for another time. Right now, here's some really good advice about how to deal with that overwhelming workload that you've got right here, right now:

Stand-out advice amongst many great pieces of advice:
"Give your boss as much advance notice as possible that you’ll need an extension, and briefly explain why."

Your boss can't help you, manage expectations of others, or stop people piling more work on you, if they don't know you're having problems. (That doesn't mean your boss will do any of that, you might just have a crappy boss.  But that's also for another time.)

We'll come back to preventing overload at a later date, because there's lots to be said about email/task/time management, saying No, to-do lists, personal productivity, efficiency, staying motivated, prioritisation, planning, building habits, changing your perspective and a ton of other things that can stop you getting so overwhelmed.  For now: read the article, take a deep breath and remember that unless you *actually* save lives for a living, nothing you do is that critical that a little delay will kill someone.  So don't worry too much :-)


Sunday 17 April 2016

Why Do You Stand Up During a Daily Scrum?

A daily scrum is also sometimes called a stand-up. The reason is obvious: The participants have to stand.  Why is this?

Easy question, easy answer (like many things in Scrum): We stand up to keep the meeting short.

This is because the Daily Scrum is intended to elicit the answer to 3 specific questions from each team member, and no more.  Frankly, when people are sat down they have a greater tendency to waffle. Standing up leads to less waffling and keeps the meeting short and to the point.  It's all about being productive and useful.

A little backup from people who have experience of a lot of meetings:

Richard Branson:

"’s very rare that a meeting on a single topic should need to last more than 5-10 minutes. If you stand up, you’ll find that decisions get made pretty quickly, and no one nods off! Plus it’s a great way to fit in a bit of exercise and stay focused on a busy day. "

The Wall Street Journal:

"Stand-up meetings are part of a fast-moving tech culture in which sitting has become synonymous with sloth. The object is to eliminate long-winded confabs where participants pontificate, play Angry Birds on their cellphones or tune out. "

Mike Cohn:

"We stand up to keep us on focus, no sitting down. When we sit down, we start stalling.....The point is to come together very focused, just a short period, and let people get right back to work. No delays." 

Hopefully this makes it nice and clear for you: Sitting down during a daily scrum = bad, standing up = good.

(Of course, there's a lot more to the Daily Scrum than just standing, and a good place to start is with this guide to daily scrums from Agile coach and practitioner +Jason Yip.)

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.