5 Ways to Measure Technical Writers

In the past I've talked about how measuring documentation is one of the hard problems of documentation and to assist in that I wrote a list of things you can measure about technical documentation, but now it's time to talk about measuring technical writers.

Obviously there are a huge number of contexts and situations a technical writer could be working in, so I'm going to focus on what this blog is about - agile documentation - and therefore look at a writer working in a scrum team.  Hopefully the general concepts and ideas will give you something to think about even if this doesn't describe the situation you're in.

An obvious problem for testing a writer is that you can't use some of the simple development measures such as percentage of unit test or automated test coverage.  Developers can be measured by whether they've got the appropriate test coverage for their code, thus ensuring that at the very least, their new code doesn't break the existing code.  But the concept of testing documentation at anything other than the syntactical level is (currently) too complicated for a computer to perform, by which I mean a computer is not able to ascertain whether new documentation semantically "breaks" the old documentation.  (There is quite a lot to be said about the difference in semantic load between natural and artificial language, but I'll leave that for another time.)  So computer-driven test coverage isn't really going to tell you much, other than that the writer has written something.  We're not really interested in that, because it's a trivial measure that is only a small degree away from the reviled "how many words has the writer written" measuring mentality.  (If you don't know why being measured by number of words is a bad thing, Tom Johnson has an excellent post on the subject, in which he explains why it leads to bad outcomes.) 

This brings us to an important secondary question: If we're not interested in measuring absolute output, what are we interested in measuring?

Generally, we're interested in measuring productivity and quality.

There's an interesting article on measuring productivity where the authors talk about using an algorithm to calculate a normalized productivity score for each writer.  I really like this approach and there's a lot of useful ideas there that are worth investigating.  However, it's an approach that works best when writers are working on the same kind of things in the same kind of situations (although to an extent you can weight scores to balance this out a bit) and the algorithm is - naturally - specific to their situation.  So let's look at some generic ways you can measure writers that are more useful than "how many words they've written".  Not all of these will be right for your situation, but at least they should give you some ideas.

1. Lead time

A classic operations measurement, lead time is the time it takes a set of inputs to move through a process.  This can be weighted against the complexity of the task as measured in story points, although it does require documentation tasks to be measured against each other which might be difficult if each writer is working in scrum teams with significantly different types of work. An obvious objection to this is that teams should not be compared by story points; you can't say that a team that does 40 points of work in a sprint is less productive than a team that does 80 points, because estimation is a matter of comparison to other items in the sprint, not an absolute measure.  Nonetheless, if your writers are generally working on the same things - e.g. topics for a help file that covers work from all teams - you should be able to weight appropriately based on historical averages.  This will also help you spot information pipeline problems if a writer regularly has to take additional time to get information that other writers get as standard from their teams.

2. Peer review scores

People make mistakes and documentation has a high semantic load, so this isn't a "100% or fail" measurement.  But if a writer regularly fails peer review for things which you would expect them to get right, such as proscribed terminology or incorrect formatting styles, this is a sign that there is a legitimate problem.  More concerning than these kind of errors (because the writer just needs to learn the rules and follow them) will be errors of comprehension or explanation.  If the peer reviews reveal that a writer regularly writes unclearly or doesn't appear to understand the topic, you've got a problem that needs to be resolved.

3. Support tickets

Related to peer review scores, the number of support tickets that could have been dealt with in the documentation indicates how much the writer understands the user story that they're documenting.  There are a myriad reasons that you could have increased support tickets around an area a writer was working on, so be very careful here.  Perhaps the subject matter is extremely difficult, perhaps 1 or 2 customers haven't read the documentation and are flooding support with tickets that they shouldn't, perhaps the user story didn't capture the user pain correctly, and so on.  However, if the support tickets simply indicate incorrect, incomplete or poorly written documentation then there is a de facto problem to be addressed.

4. Technical debt

Take a measure of the existing technical debt, to cover known missing, incomplete or out of date documentation that the writer is responsible for.  Measure this on a regular schedule that is short enough to catch a problem but long enough to allow for short term fluctuations such as holidays or sickness, such as once a quarter or every release.  You're looking for a trend that at a minimum doesn't go up.  This means that the writer is not making the technical debt worse.  Whenever a writer is working in a topic with known technical debt they should be able to improve it (as a general rule of thumb, not a cast-iron certainty) and the trend should go down over time.  If the trend stays level, the writer is either very busy or adding as much debt as they're paying; if the trend is upwards then the writer is adding debt and you've got a serious issue to deal with before it gets any worse.

5. Commitment vs complete

Does the writer complete the documentation they've committed to at the beginning of the sprint?  There's an assumption here that your company's culture is such that the writer feels comfortable refusing to commit to a sprint if there's too much documentation, or not enough information about the documentation requirements, to commit, although most writers I know work in a dirty agile scenario, so maybe this is unrealistic.  However, if you can use this measurement, it will tell you about the writer's ability to estimate and their willingness to push through to get things done.  Of course, it might also tell you that the whole team struggles to complete, which is a different issue.  But it's important for a writer to be a "completer", so make sure you know whether your writer is getting things finished.


All 5 of these measures could be expanded on, but every situation is different and these are intended to be generic measurement points for agile writers.  All of them allow you to measure trends over time, which is essential for performance management.  But they're not the only things you can measure, so what other measurements do you find useful?  Share them in the comments.

7 Reasons We Don't Need the 5 Scrum Values

In the latest update to the Scrum Guide, Ken Schwaber and Jeff Sutherland have added 5 Scrum Values, which are:

• Courage
• Focus
• Commitment
• Respect
• Openness

You can read the official press release here.   Let's start with the positives: It's good that the Scrum Guide is updated when necessary, and it's good that Schwaber and Sutherland take into account user feedback about what should be changed (it wouldn't be very agile to do otherwise, one might think).  It's also good that the 222 people who voted for the "Add the 5 values in" suggestion got what they wanted, as they are presumably highly engaged with Scrum and are therefore important ambassadors and evangelists for this framework that we know and love.

Gunther Verheyen has a good piece on his blog about the 5 values and why he thinks they're a good idea.  A key section reads:

"[The 5 values] relate to the ethics of Scrum, thereby - from a social point of view - turning Scrum into a value system. Although not invented as a part of Scrum, or exclusive to Scrum, these values give direction to our work, our behavior and our actions."

Gunther goes on to provide some detailed notes about each of the 5 values and how they guide actions and behaviours.  It's well worth reading and I'd encourage you to do so, especially as he seems to have enunciated a general feeling amongst proponents of the 5 values about what the values are intended to do, and how they are expected to drive the behaviours of the team.

However......

I'm struggling to see the value of these 5 values, despite the admirable analysis from Gunther and many others (I'm using Gunther's article as a representative of this type of analysis because I think he's provided something of an exemplar, not because I want to pick holes in his work specifically). 

There are 7 main reasons why I think these values overstep the remit of the Scrum Guide.  The most obvious one is:

1. They're lame.  The obvious complaint, but worth spelling out.  When you have a team of people who's primary skill set is technical, making them live by a set of values called things like "Courage" and "Respect" is not going to be well received.  I can count on the fingers of one hand the developers I've met who thought "values" were important, and all of them wanted to be promoted to management.  Management used buzzwords like "values", so values were important to these developers. They weren't important to any other developer.  These are cringe-worthy for many people, especially people who work in dev teams.  We're not the kind of people who generally talk about "values".  We talk about code, sci-fi and coffee.  I'm sorry if that sounds like a cliche, but it's a cliche because it's true.  If you think that talking about values is important and useful, then good on you and I would never try to stop that.  But for a lot of people a discussion about "values" is in the complete opposite direction of anything useful or enjoyable.  Like creating software.
2. They're not Scrum. Scrum is an adaptable framework, not a value system, ethical system, or social system, and adding these values moves Scrum away from being a framework towards being one of these systems instead.  Values are not adaptable or flexible.  Systems are not adaptable or flexible.  Frameworks are adaptable and flexible, especially ones with a core mantra of "Inspect and adapt".  By their very nature, values normally end up codified, ossified and rigid, and it will not be long before the righteous start claiming that if you don't show these values then "you're not doing it right". 
3. They're patronising. If you expect me to be courageous, focused, committed, respectful and open, I've got good news for you: I already am, because I'm a professional.  I'm also honest, hard-working, enthusiastic and thoughtful, again, because I'm a professional. Things I'm not: Lazy, stupid, cowardly, in need of being patronised.  Because I'm a professional.  If you work with people who don't already display these values, adding them to the Scrum Guide won't change their behaviours in the slightest other than potentially making them resentful and grumpy. People who are professional don't need to be told to be these things, people who aren't professional won't pay any attention to them.
4. They're insidious.  Following on from people who don't already display these values, there is more than a whiff of the thought police about these values. If you can't see how someone in a position of power could use vague values like these to reward their favourites unfairly and punish their trouble-makers equally unfairly then you need to get better glasses.  "Why didn't I get my bonus?" "Sorry Kevin, you just didn't seem committed enough."  This is why people want quantitative achievements on their objective lists, not qualitative behaviours and competencies. These values add a legitimacy to the notion of measuring behaviours that just can't be measured.  The opportunities for abuse with this sort of behavioural standard are legion, and they will be taken by more than a few incompetent/unscrupulous people.  The ones who will suffer will be the people on the scrum team.
5. They're random. Why these 5 things?  Why not say people should display "trust", or "honesty" or any one of a thousand positive behavioural nouns that would benefit a member of a scrum team?  Why not just say "I will work hard to achieve our goals without being a complete arse to the people around me."?  That would actually be a more accurate requirement, and less patronising.
6. They're aimed at the wrong people. I've talked before about how the power of scrum doesn't lie in the scrum team, and these values are a precise demonstration of this.  It doesn't matter what values the scrum team try to embody, because they aren't the ones who will make a scrum implementation succeed or fail.  Scrum requires a cultural change of the whole company, not just the people who design/write/test/document the code, and by pushing these values onto the team all that will happen is that they will become just another stick with which to beat that team if something goes wrong, even it what went wrong did so because of an agile failure outside the scrum team.
7. They're additional overhead. Scrum is not as lightweight as some people would suggest.  It is a complete cultural change that requires your company to do some serious shifting around of authority and responsibility if you're going to do it properly.  I'm totally onboard with that, but let's not pretend Scrum is no burden to bear.  Adding these values only increases the amount of cultural change and behaviour modification that moving to Scrum, or getting good at Scrum, requires.  Given that the success rate of Scrum projects is only 62% (according to the 2015 State of Scrum report), this is an overhead that's not needed.

So it's far to say that I'm not a fan. 

These values will be great for anyone who makes a living out of training or consulting in scrum, because they're vague enough to be endlessly analysed and written about without necessarily adding anything - ironically - of value.  This makes them an ideal subject for another day's expensive training, as well as extra consultancy fees for analysing your company's culture and explaining how the Scrum values could really, really help.  Would anyone be really surprised if training/consultancy companies started offering Scrum Values courses at a large amount of money per attendee?  No, me neither.  I'm sure that Schwaber and Sutherland genuinely believe that these values are an important addition to Scrum, and in their rarefied atmosphere they might well be right, but on the ground I can't see this being useful or beneficial at all to most teams. 

If you want to change the attitudes and behaviours of your team members, you don't have to be a psychologist to predict that "values" are not going to have this effect.  Try coaching, mentoring and, yes, managing your staff to help them get where they need to be.  Don't rely on an arbitrary set of values in a development framework to do that hard work for you.

Agile Product Ownership in a Nutshell

If I was a betting man, I'd lay money that the most likely weak spot in any given company's agile implementation is the lack of Product Owners, or at least the lack of properly trained Product Owners.

A common situation is that Product Managers or Project Managers (PMs) become Product Owners (POs), and it's more of a change of job title than a change of methodology.  PMs are used to aiming for deadlines, often with a narrow view of what's important to have done by that deadline.  POs aim to get the most important work, as measured by a business value calculation (BVC), done first.  Deadlines become just another factor in the BVC, as often deadlines are self-imposed and a person who made a promise to a customer to secure a sale will just have to go back to that customer and apologise.  (That potential loss of company reputation is another factor in the BVC, but let's not get side tracked.) That's not to say that deadlines aren't important, but some deadlines - e.g. an accountancy product needing to meet the requirements for tax legislation that's coming into force on a specific date - are much more important that others.

Similarly, the BVC acts as a black box for the type of work, so where a PM will focus on their specific project or user group need, a PO will treat legislative, statutory, customer requirement, project, bug fixing and technical debt work in exactly the same way.  All types and pieces of work are measured using a BVC, and if fixing a piece of technical debt has more business value than a customer requirement or meeting a project deadline, then so be it - the technical debt gets done first.

This transition from deadlines and narrow views to business value and a holistic view is definitely difficult for some people to get their heads around, especially in companies that run dirty agile. If you, or someone you know, struggles to understand what, how, when and why a PO does what they do, then the video below is for you.  It's only 15 minutes long but it's worth it no matter what your deadlines are:

What Order Should Sprint Meetings Be In?

I had an interesting conversation recently regarding the order of sprint meetings, and whether it mattered what order the review and retrospective took place.  This lead to a wider conversation about whether you could do review, retrospective and planning in only 1 or possibly 2 meetings.  That all sounded a bit "dirty agile" to me, which is normally a good cue to re-examine my assumptions to see if I've been thinking too rigidly.

In my head, the sprint ceremony order is one of the inviolable "rules" of scrum, so much so that it didn't really occur to me that people might think differently.  It's just one of the default assumptions I have about how scrum is done, rather than a subject for debate.  After discussing the matter I still don't think this is something about which you can be flexible, although this is not stubbornness so much as the lack of a compelling argument to the contrary. I'm open to persuasion if such an argument exists though.

The agile mantra of "Inspect and adapt" is high on my list of principles, so to that end I'll lay out the order of sprint meetings and why they need to be discrete meetings, and if anyone wants to chip in with counter suggestions I'm all ears.

First, the facts as I see them:

1. The Review should happen on the last day of the sprint.
2. The Retrospective should happen on the last day of the sprint.
3. The Retrospective should take place after the Review.
4. There should be a break between the Review and Retrospective of at least an hour.
5. The Planning should happen on the first day of the next sprint.  
6. The Planning for the next sprint should never happen until the Review and Retrospective from the previous sprint have been completed.

And now the justification for each of those points: 
 
1. The Review can only happen once all of the sprint stories have been completed and not before.  Therefore the Review needs to happen at the end of the sprint.  If all of the stories in the sprint have been completed before the end of the sprint then either additional stories can be added - if there's adequate time to complete them before the end of the sprint - or the team can groom the backlog, triage support requests, refactor code, and any other tasks that don't impact the sprint velocity. (If a task impacted the sprint velocity it would be story-pointed and as such be a story that was added to the sprint.) 

The Review will already be a recurring appointment in the stakeholders' calendars and as stakeholders are often in demand it shouldn't be assumed that bringing the Review forward will be simple case of sending out an updated appointment.  This is especially true where stakeholders are many and/or senior.  But this a practical objection, albeit a sensible one, and as such doesn't have the force of compulsion.  The compulsion should lie in the fact that moving the review forward serves no purpose. Assume that the Review is moved forward.  Either the Retrospective is moved forward as well or it is not.  If the Retrospective is not moved forward then moving the Review has served no purpose because the team still has to wait for the Retrospective. If the Retrospective is moved forwards as well then the end of the sprint must be moved forward, otherwise the team will have to wait for that instead.  If the end of the sprint is moved then the next sprint must be started.  This means that your sprint will start on a sub-optimal day.  Any teams working on the same sprint cycle will now be on a different sprint cycle.  The team's velocity calculations will no longer be valid.  Your customers - assuming you release an increment at the end of each sprint - will have to change their processes to accommodate a different cycle. There are other issues that will arise depending on circumstances, but all of them revolve around disturbing the cadence and rhythm of the sprint cycle. Scrum is predicated on having this cycle as part of the methodology for successful teams; there appears to be no benefit to disturbing it.


2. Assuming that the arguments for the timing of the Review ceremony hold, the same will apply to the Retrospective.  Therefore let's look at the order of the Review and Retrospective meetings.


 3. There is an argument that holding the Retrospective before the Review allows the team to deal with what went wrong and then finish the sprint on a good note with the Review where they can show off their work to the stakeholders.  I like the sentiment, but not the logic.  The argument hinges on 2 unfounded assumptions, namely that the Retrospective is all about what went wrong and therefore is a necessarily less than enjoyable meeting, and that the Review will always go well.  Neither of these assumptions stand up to scrutiny, regardless of personal experience.  That's not to say that for some people Retrospectives are a generally unpleasant experience, nor to suggest that every team has had a Review that didn't go well. But my assertion is firstly that a Retrospective should neither focus purely on what went wrong, nor be an unpleasant experience, and secondly that the assumption of future Review success based on past glories is hubris that will inevitably bite the team at some point in the future.

The long and the short of it is that the Retrospective should be honest but not unpleasant.  It's true that if you are the kind of person who doesn't take criticism well then you might not like hearing that something you were responsible for didn't go well, but frankly that's your problem and you owe your team a more mature attitude.  Likewise, if there is a team member who revels in shoving failure down the throats of their team-mates that's not pleasant either, but the group should combine to shut that person down (or in extremis remove them from the team).  Being part of a scrum team means learning and growing through an iterative process. You have to be open to that.

Likewise, Reviews can go wrong.  More importantly, they can teach you things you didn't know if you have active stakeholder participation (which you should have!). Either way, the Retrospective is where these things should be discussed and actions created.  This can only happen if the Retrospective happens after the Review.


 4. Ok, fine, we do the Review then the Retrospective.  We'll do them in one meeting and get it all out of the way, ok? No, not ok.  The Retrospective should be a separate meeting, because what comes out of the Review needs to be thought about before having the Retrospective.  Also, people work better when they've had a break, and the Review can be tiring if you've got a lot of questions to answer from stakeholders.  Give people a break for an hour or two, let the Review comments sink in, then do the Retrospective.  You'll all get more out of it that way


 5 If points 1 - 3 are assumed, then the timing of the Planning meeting becomes self-evident.  You can't complete any stories unless you've got stories to work on, and to get your stories you need to have a Planning meeting.


 6 Well, why can't we plan our next sprint if we've got some spare time? Because actions will come out of the Retrospective, and quite possibly the Review, and these should be captured in your task management system and might need to go into the next sprint.  You can groom items on the backlog, and that includes estimating story points and task time, but you won't know what the final priorities are until all of the previous sprint has been completed and the Product Owner has updated the backlog with the latest priorities.


Hopefully that explanation provides solid reasoning for you, but don't be afraid to drop a comment below if you disagree!

Agile vs Dirty Agile

In my last post I mentioned that there was a dearth of simple "agile vs non-agile" comparison graphics, and presented one of my own.  I'm now happy to present the first - and currently only - Agile vs Dirty Agile comparison graphic:

  

Why are Multi-Functional Teams Desirable?

In the past I've talked about multi-functional teams being the unicorn at the heart of scrum, i.e. very desirable but essentially mythical.  I've also written a post explaining my take on the reason why multi-functional teams are so hard to find, but an article from Darren Wilmshurst has made me realise that I've never talked about why multi-functional teams are desirable in an agile environment (actually, required, if you don't want to do Water-Scrum-Fall).  But before I go into this, I need to share a little bit about the writing process behind this blog, for reasons that will hopefully become clear.

Some of the posts on this blog are articulations of good practice, some of them are based on years of experience, and some of them - like this one - spring from a thought that occurs to me whilst I'm reading/writing/doing something in relation to agile.  If you've ever spent a lot of time immersed in a conceptual framework, you'll hopefully understand how everything you see and hear that has any relation to what you're immersed in has the potential to send your mind off in a direction you'd never thought of before.  This is the case with this blog; so much of what I write is the result of seeing everything professionally through the lens of trying to understand and then explain how and why agile things work the way they do, and that constantly sparks off ideas for blog posts.

Right then, that's all well and good, but what does it have to do with why multi-functional teams are desirable? Well, it's this: When I realised that I'd never written about this topic, I initially thought that it would already have been well covered in the blogosphere by other writers, so maybe I was just mentally riffing on something that has been fully documented elsewhere. This has happened before, and I didn't feel I had anything to add to the conversation, so I didn't write a post.  But in this case, maybe someone has posted extensively on this topic, but I can't find those posts.  There are posts that explain some of the practical benefits of a multi-functional team within an agile process, such as greater efficiency, less waste, cross-fertilisation of skills and ideas, and so on, and for a lot of people, maybe most people, these benefits are an acceptable end in themselves.  No more explanation is required.  But I'm more interested in articulating why those benefits are indeed benefits.  What is the conceptual paradigm behind those benefits?  What is the ground for the article of faith that says multi-functional teams are good? 

Perhaps "article of faith" is wrong, but it captures the essence of my point.  A more accurate statement might be to say that the concept of multi-functional teams has become one of the boundary conditions for what defines an agile team as agile, and, therefore, if you think agile is good, you must by default think that multi-functional teams are good.  And that makes sense, because nothing is more closely associated with agile than the concept of the multi-functional team.  Multi-functional teams are the hinge on which the agile process turns; without that team, you can't describe yourself as agile.  And yet, this boundary condition is so universally accepted without question that I can't find much written about it, which seems like an oversight to me.  I'll try to address that here.

In a previous post I talked about how agile methodologies like scrum and Kanban might be more suited to startups than mature companies.  The heart of the piece was as follows:

"As a company grows though, employees become more specialised to increase efficiency and quality.  This is an economy of scale that basically turns any suitably large company into a form of production line.  Processes, procedures and standards provide not only the structure of the company which analysts can constantly study for new ways to increase efficiency (read: profits), but also the conceptual conveyor belt along which the product passes from conception through delivery and implementation to maintenance and support.

But scrum is the antithesis of this production line ethos with its proscriptive standards and linear flow.  Scrum suggests, nay, demands a multi-functional approach to production within the scrum team, and that cannot happen if the scrum team is made up of specialists. "

Individual specialisation is the opposite side of the coin to multi-functional teams.  It is the difference between the Henry Ford production line and the farming collective.  There is an inherent tension here between the command-and-control, profit-driven efficiency of the production line, and the self-organising arrangement of a series of individual strengths and weaknesses for mutual benefit in the farming collective.  The production line values efficiency over everything, and this is why it makes sense for a startup to move towards increasing specialisation.  The key to a successful business, in the short to medium term, is to leverage a good idea such that enough revenue is generated to sustain that business as a going concern and provide enough profit for the owner to make it worth their while to continue.  The best way to leverage a good idea which you've had initial success with is to hire specialists who can design, build, support, market, sell, and so on, while you focus on the good idea you had.

But in the long term, the key to a successful business - especially in an industry as fast-moving and competitive as software - is innovation, not efficiency.  That's not to say that efficiency becomes unimportant, because it doesn't.  It's just that efficiency is only useful so far as your products are delivering what the market wants.  Even Ford, the company that made the production line famous, has the 2nd highest R&D budget of any company in the world.  Why?  Because without innovation their profits will wither and die.  Not many people want a 1980's Ford, no matter how efficiently Ford can make them, when they can have a 2015 Toyota, so Ford spends billions every year to make sure that they have a competitive range of products for people to buy, and thus ensure their long term success. 

And here's something important: innovation does not have to be mutually exclusive from efficiency.  Nor does innovation have to flout a company strategy, or a divisional goal, or have no command-and-control directing it. As long as the team that is innovating knows what their boundaries are, you can let them get on with it, like a black box.  Innovation might not be something that can be made more efficient in the way that piece work on a conveyor belt can be, but you can most definitely give a team of people the right conditions to innovate and improve their chances of coming up with the next big idea.  If you do some research on the topic, the same recommendations for creating an environment that fosters innovation come up time and again:

 - A culture of trust where people know that their ideas are valued;
 - A culture of empowerment where people won't get in trouble for trying something new;
 - A culture where the leadership actively encourages and rewards innovation.

In other words.....an Agile culture. Agile has all of these things, and although many people have to put up with working in Dirty Agile, anyone lucky enough to work in a company that has properly bought into Agile should have experienced these 3 things.  So despite initial impressions, it is the collective that values the contribution of the individual more than the production line does, and this speaks directly to why multi-functional teams are desirable:
 
The collective allows the individual the space to innovate as part of a team.  The production line just allows the individual to do the same thing they've always done, only a bit quicker.

Agile is firmly in the collective camp, and the self-organising multi-functional team is the tool that is used to drive innovation by building trust, providing empowerment, emphasising communication and fostering a culture of collective problem solving.

That's why multi-functional teams are desirable. 

This also explains why so many companies who engage in Dirty Agile don't value multi-functional teams - they are the companies without the foresight or leadership to plan for the long term, so a multi-functional team that can innovate is never as important to them as a group of specialists who can do the same thing again and again, very efficiently.  That also saves on training budgets and career development, which reduces short-term costs, although the staff turnover rate is strangely high..... I suspect that I don't need to gild this lily any further!

Perhaps you should ask yourself the question: Are you working for a company with a 1920's Ford production line, or a company with a 21st century Ford R&D department? And which one would you rather work for?

Documentation Shouldn't Be Used to Cover Technical Debt

In my previous post, I talked about documentation having technical debt.  Normally this debt is a burden on the users, and therefore the customer support team (this is one of the reasons why documentation has value, rather than just a cost, but I'll expand on the benefits of documentation in a future post).  But technical debt in the software, whilst potentially being a burden on customer support - and indeed customers - can become a big burden on documentation, and lead to more technical debt in the documentation itself.  Allow me to clarify. 

If your software:

• Does something when it shouldn't do;
• Doesn't do something when it should do;
• Does something in an unexpected way;
• Does something in an incorrect way;
• Is unnecessarily complicated;
• Is not designed with ease-of-use in mind;
• Causes an unnecessary manual intervention;
• Causes an unnecessary manual correction;
• Causes the user any problem that requires them to contact Customer Support;

Then your software has technical debt that should be explained in the documentation.  That's a whole bunch of known issues that have to be documented in at least one place, and maybe more (for example, on a dynamic customer-facing website and also in the release notes), as well as additional documentation effort required to talk the users through bad design or bad implementation.  This is a burden on the documentation team.  In a very real sense, development's debt is therefore documentation's debt, because we (are one of the teams that) have to pay the interest on that debt until it is paid in full by development.

On top of this, the additional documentation that has to be done has to be recorded and monitored, so that as the development team pay back their debt in code, we can amend our documentation to match.  As soon as this happens, there is a technical debt in the documentation, because it no longer matches the software.  This debt may only last until the writer has completed the documentation task that go with the development task, or, as happens more than it should, a developer might see and fix something whilst they are working on the code line but not mention it because they didn't realise it was documented anywhere, and the documentation debt never gets paid.

A simple example might be that the documentation states that a process may take some time if there is >= 10000 records.  A developer is working on fixing an unrelated issue in this process, and whilst she's in the code she realises that a minor change to a While loop will speed up the process significantly, especially for larger record sets.  She makes this change, as well as fixing the unrelated bug, documents the bug fix (but not the speed change), and moves on to the next task in the backlog.  Bang, your documentation is now incorrect, and there is no way you'll ever know about it.  Meanwhile, your customers "know" that this process is not as fast as it should be, and this decreases their satisfaction with your product.  This is a small error in your documentation, and the customer's satisfaction decrease is equally small, but if you multiply this by 10, or 20, or 50 small errors then their cumulative weight can make your documentation seem inaccurate and your product quality seem poor.


The other large burden that technical debt can place on documentation is when the software is unnecessarily complex.  A friend of mine once described a product he worked on as suffering "death by a thousand parameters", as every piece of additional functionality that a customer wanted was parameterised so that the other customers could continue using the product in their own way.  This led, as you can imagine, to a ridiculously complicated system, and was caused entirely by an unwillingness to say no to shouty customers, and an equal unwillingness to make long-term strategic decisions that would benefit the majority of customers instead of just the most obnoxious complainers.  The fate of this product was entirely obvious to all but those who's unwillingness led it to its inglorious endpoint.  This situation is a somewhat extreme example, and I suspect it's particularly prevalent in a Dirty Agile situation where the Product Owner is not the hawkish gatekeeper they should be, but it casts a light on a problem that writers face in many companies - the expectation that technical debt has been "dealt with" as long as someone has documented it.

I don't know how to say strongly enough that this is wrong, but maybe Scott Adams can help:

'Nuff said....

 







That kinda sums it up right there.  The scary thing is that some people need that explained to them, or they see the superficial humour but don't see it as a genuine problem that needs solving.  If as a writer you find yourself spending any significant time writing documentation to cover the technical debt of your software, then that software will be unlikely to provide you with a long term career.  No company with any pretensions to success will have that level of debt in their products, because they won't get the confidence of their customer base, and without that confidence they won't make the sales that will sustain the company in the long term.  On top of that, the cost of maintaining a product with significant technical debt is much higher than the cost of maintaining a product with low levels of technical debt, so you get the double whammy of low customer confidence leading to low sales income on the one hand, and high maintenance cost on the other.  Hopefully you don't need to be a business guru to work out the consequences of this....

Is Agile's "Good Enough" the Enemy of Great Documentation?

The aphorism "Perfect is the enemy of good" has been around for at least 250 years (and possibly a lot longer), and whilst it was probably not directed at the software development community, nonetheless it has been taken up with gusto by agile adopters in recent years.  It acts as a rallying cry in favour of working software over exacting algorithmic efficiency, completion over perfection, time-to-market over end-to-end scope.

But what does it mean?  And how does it impact writers who produce documentation in an agile environment?

Let's take an example. Imagine your application has a search function.  If a user enters their filter criteria and hits the button, any matching records will be returned in 0.3 seconds or less. This seems quick, but your optimisation team are confident that if you give them 2 months then they can shave a bit off this and get it down to 0.2 seconds.  Should you let them do this?

Answer: No, unless every other well-travelled part of your application is as optimised as it is possible to be (which it almost certainly isn't).  The reason is that 0.3 seconds is well within the realm of "good enough", because not only is your application returning records literally within the blink of an eye, it's also returning records faster than the speed of thought.  As the speed increases (i.e. the time to display the results decreases), the Cost/Benefit curve flattens out. In other words, after a certain point the benefits of optimisation to the users are not worth the cost to the developers.

This is an example of where "perfect" (increasing the speed until it is mathematically impossible to squeeze out any more performance) is the enemy of "good" (providing enough performance that users receive the results in an expedient time).  The more time you put into "perfect" in one area, the less time you have to spend on "good" in other areas.  For you developer types, "good" is getting a sorting algorithm to O(n log(n)), whereas "perfect" is trying to get it to O(1).  Leave that to Google or MIT - you've got the rest of the application to code and a heap sort will do fine, thank you very much.

Well then, so far, so good.  Agile says don't go crazy on the perfection, make your software good enough to make the users happy, and move on to the next task.  That sounds sensible, right?  Allow me: Yes, it is sensible.  But - and here's the rub - good is the enemy of perfection, but it's also the enemy of great. If Google had just settled for "good", do you think they'd be the multi-billion dollar behemoth they are now?  No, they wouldn't.  The irony of taking the concept of "perfect is the enemy of good" too far is that you can try to make your "good" approach "perfect".  In other words, you can take a philosophy that counsels against an extreme and apply it in an extremist fashion.  "Perfect is the enemy of good" can become "Never do anything as well as you can, because that will stop you producing other things.", and suddenly everything you do is just "ok".  Very few companies, or people, have excelled by just being "ok". 

Now admittedly, because the power of scrum doesn't lie in the scrum team, it's entirely possible for the people working outside of the team - designers, architects, analysts, etc - to focus their time on producing great designs, great frameworks, and great specifications, and therefore the scrum team can implement a "good enough" version of a "great" vision.  This seems like a decent balance, because the design/framework/vision provides the "great" and, as long as "good enough" doesn't become "that'll do",  the scrum team can implement it in a way that meets users' needs and still has a quick time to market.

But this is all very developer-centric.  How about the technical writers, I hear you cry?  How do they distinguish between "perfect" and "good" and aim for "great"? Who's providing our great design and vision?  I've talked previously about technical writers having design responsibilities that developers often don't, and this is one of those times when this issue rears its ugly head.  It's unlikely that working writers will have both the knowledge and the time to perfect documentation designs that provide some form of "great" overarching framework they can slot their content into.  This means that a lot of writers are working within a documentation framework that is "good" (or even "ok" or "bad") rather than "great", and they also get the double whammy of working in a team that prioritises "good enough" over "great".*  In other words, there isn't a point of brilliance around which writers can weave their content.  In this sense, Agile's "good enough" can put writers in a position where they can never work on doing something "great", and that kind of defeats the object - "good enough" should be used for the everyday, to leave time for "great" in the things that really matter.

My experience of technical writers is that they are - usually, not always - detail-oriented, conscientious and prone to perfectionism.  This makes sense, because these traits are pretty much requirements of the job, and if these things don't come naturally to you then you need to have the self-discipline to impose them on yourself if you want to be a good technical writer.  There are no objective metrics on what constitutes "good writing", so although there are various principles one should adhere to when producing technical documentation, and classic tomes on what constitutes "writing well" in general, it's very difficult to provide a scale or yardstick against which a piece of writing can be objectively measured.  This means that perfectionist tendencies can make a writer disappear down the rabbit hole when it comes to deciding when to put the keyboard down and stop making edits.  Because here's the guilty secret that writers all know: No piece of writing has ever been finished.  Sure, it's been drafted, re-drafted, reviewed, released, published, critiqued, amended, re-published and plagiarised, but it's never been finished to the point that writer couldn't change it some more.  This is as true of a help file as it is of a novel.  Code can be considered "complete" when it provides the specified functionality, and there is mathematical certainty about the boundaries of efficiency and concision so at some point there is at least a theoretical line past which the developer cannot improve the code.  Writing provides no such boundaries.  We can endlessly refine and reword and re-jig a paragraph until our head spins, and no-one can tell us that we can't improve it.

All this means that the writer with a leaning towards perfectionism - i.e. most of us - can be caught in an endless cycle of doing just what's necessary for the documentation, and no more, even though that goes against all of their instincts.  This is compounded by the fact that documentation is at the end of a linear process and as such, we are often squeezed for time to complete at the end of a sprint, or series of sprints.  This is typical in a Dirty Agile situation. There are ways to offset this, such as agreeing time boundaries with the rest of the scrum team, implementing proscriptive standards to make you quicker and more consistent, and insisting on having a hardening sprint where no new work is developed, but for writers in this unfortunate position, there may be little chance to focus on doing something "great". 

I can offer no advice, but I can offer a warning: If you never get the chance to do "great" work in your current position, find another place that'll give you that chance, because with nothing to strive for, work quickly becomes a slow, boring march to an unfulfilled career and a retirement full of regrets.  Don't be that person.  You won't like it.





 
* - I'm sure lots of developers are also in this situation, but I believe that it is more likely for writers to work in a team where they have no externally-designed "great" framework or vision, then it is for developers.  Fee free to contradict me in the comments though.

99% Dirty Agile

I recently attended the launch of the BCS's latest offering, Agile Foundations: Principles, practises and frameworks in London. As this is the official companion book to the BCS Agile Foundation Certificate in Agile, you might think that it's only worth reading if you are studying for that qualification, but you would be incorrect.  Having read it, I can heartily recommend it for anyone with an interest in agile methodologies; there will be very, very few people who have a broad enough range of experience that they won't learn something new, interesting and useful from it.  However, a full review and/or evangelical recommendation is not the point of this post, and neither is a forensic examination of how it treats the topic of agile documentation (which will come at a later date.  Try not to get too excited, it's bad for your heart.).  The point of this post is to relate the important realisation I had on the way back from the launch.

After the book overview, case study and Q&A (all very interesting) there were a few drinks and some chatting amongst ourselves. During this, I had a conversation with Mike Short from radtac where I asked him about the problem of Water-Scrum-Fall and how you turn the specialists that you find in mature companies into the generalists that you really need to make agile effective.  Mike is someone who (amongst other things) specialises in changing cultures and mindsets into ones where agile can flourish, so asking him about the minutiae of linear development models is a bit like asking Alex Ferguson for a detailed discussion about methods for improving sprinting speed - it's relevant to what he does, but he operates at a different conceptual level.  That alone was an interesting realisation, but not the important one.

No, the important thing to come out of that conversation, in fact out of the whole evening, was that what I know about, what I write about on this blog, is not what could be called "pure agile".  I'm specifically not saying "theoretical agile", because radtac clearly have a theoretical model, or, more precisely, multiple agile models that overlap, and they take the most appropriate parts of these models to help a company achieve their agile paradigm shift in the most effective way for that individual company.  And it works, and radtac are rightly respected for it.  Saying "theoretical agile" is almost like a sneering riposte, as if I'm suggesting that the wimpy boys study theory, while REAL MEN DO AGILE IN THE REAL WORLD!!!  YEAH!!! *muscle flex*  And to be clear, I'm not saying that (but *muscle flex* anyway, because hell yeah). I'm also not knocking the theory of agile, or those people who adhere to an implementation that is very close to the theoretical model, because that's what you're supposed to do.  What I AM saying is that what I know about is agile in a world where companies either can't or won't invest in making the paradigm shift to a fully agile company culture. Time and time again I read questions and laments from people on forums facing the same problems I've faced, and friends in other companies have faced, and these problems are almost always ones that Ken Schwaber would solve by saying "Scrum, Scrum and more Scrum!"  But what do you do when you aren't in a position to influence the decision to fully commit to agile as a company, when "Scrum, Scrum and more Scrum!" isn't an option?  How do you solve the problems that come with being an agile team without an agile company around you?

The answer is: Dirty Agile.  You might not be able to implement the wide-scale changes that agile requires to be truly effective, but you can damn well be as agile as possible in your specific circumstances.  So you struggle with people who don't "get" agile, you try to persuade and evangelise, to put in place processes that will help you and your agile team be more agile, and all the while the non-agile people are still pushing you and pulling you in the same non-agile way they've always done, whilst claiming that they don't really understand agile, but somehow still managing to find any way they can to push the blame for their problems onto your agile set-up and thereby both undermine your efforts to be more agile AND give you more work to do.

Purists might say that this isn't agile at all, that it's just a pale imitation, and there's some truth in that.  But everyone who's worked in dirty agile will recognise it, and know how painful it is to struggle valiantly against the ignorant, and the lazy, and the wasters, and the blame-dumpers, until the motivation is gone, the velocity is gloomy, and the original nay-sayers are laughing in their sleeves at your crazy notions of time-boxed iterations and prioritisation before specification.  They told you it wouldn't work, don't you remember?

*sigh*

We still believe in agile, but it seems so.....hard.  And far away.  We're the ones with our noses pressed up against the window and drooling, like Dickensian urchins outside a cake shop, or developers wistfully staring at Google's careers page.  We are the 99% of agile adopters who gaze longingly at the cool glass towers of the1% who've achieved agile nirvana, and imagine how good it must feel to be really, truly, madly, deeply agile.

I feel your pain, my friends.  This blog is for you.