AgileTheDocs Presentation Slides and Notes (5th Dec 2016, London)

The lovely people at GDS, in association with Write the Docs, put on a great one day mini-conference, Agile the Docs, on 5th December in London.  I was asked to present on whether documentation was in the definition of done and I was more than happy to oblige.

Without further ado, here are the slides I used, and here are the notes (I haven't done a lot of editing or formatting on the notes; the links below contain everything I talked about in a more comprehensive - and formatted - way).

If you're interested in learning more about this topic then check out the following articles:

• Should Documentation be in the Definition of Done?
• Factors that Determine if Documentation Should be in the Definition of Done 
• The Unicorn at the Heart of Scrum
• What is Water-Scrum-Fall and is it inevitable?
• Why Aren't There More Multi-Functional Teams?
  
  

Thank you to Trisha, Rosalie, Jen and Lydia from GDS, and Kristof from Writer the Docs.  You organised a short, sharp, interesting conference with interesting and diverse speakers, in a good location, at a sensible time, near a decent pub and a tube station.  Top work all round.

On a side note, the BRDC were having a benefit lunch/gala thing in the same conference centre we were, and this was parked outside:

It's an impressive machine in the flesh. And I saw Nigel Mansell in the corridor, which was pretty cool.  He looks exactly the same as he did when he won the F1 championship 24 years ago (except for the 'tashe, which went a few years back.).  Exactly the same. Either he's aged very well or he looked a lot older than his years when he was an F1 driver.

Anyway, Agile the Docs.  Really enjoyed it and looking forward to attending the next one. If you've got questions or thoughts on the presentation use the comments below or tweet me @agiledoc.

Some Notes on Moving Content to Confluence

Confluence is a super-charged wiki from Atlassian, the same company that makes the popular issue tracker, JIRA.  As you'd expect with a normal wiki, its most popular function is as a knowledge base, documentation hub and FAQ location, but due to it's tight links to JIRA (and other Atlassian products) it's also used for showing sprint reports, burn downs, burn ups, work in progress, and lots of other reports using data taken straight from JIRA.

In this post we're going to focus on the traditional wiki usage: documentation and knowledge management, and specifically some do's and don'ts when moving existing documentation and knowledge assets into Confluence.  Some of the points below are specific to Confluence, some are best practise whenever you're moving knowledge from one place to another, but they're all born of experience and hopefully they'll help you avoid some of the pitfalls.

The most important points first:

• If you're a technical person, get a content person in before you move anything.  They'll spot issues you won't. 
• If you're a content person, get a technical person in before you move anything.  They'll spot issues you won't.
  

I'm more of a content person, and having some technical people (i.e. developers) around helps immensely.  A developer's first thought is always "How can I do this through code?", which means they're much better at spotting situations where a batch file or a regex or some CSS will make everything a lot quicker and less manual.  When I was looking at moving documentation from some internal wikis, it was developers who helped me find the appropriate export functionality and worked out whether I could take that format and import it into Confluence, potentially saving me weeks of work.

Which brings me neatly on to:

• Automate as much as you can.

This means using export tools in your current location (e.g. wikis, CMS, document repositories, etc), and also Confluence's excellent built-in Word import functionality.  There is a Universal Wiki Converter which is not supported by Atlassian because it's a 3rd party tool, but the fact that the link for it takes you to a place on the Atlassian domain should tell you they think it's useful.  It doesn't work on every wiki, but if it does work for your wiki it will save you a lot of time.  If instead of, or as well as, wikis you've got lots of Word documents to import, the Confluence Word importer is brilliant.  It's really good at importing formatting and layout, as well as features like tables, images, links, headers, footers and diagrams, and it's really quick to boot.  Oh, and it will create new pages every time there's a heading in your document, if you want it to, even down to being able to set the level at which new pages are created (e.g. it will create new pages every time it finds a Level 1 or Level 2 heading, but ignore any other heading levels).  The Word importer has saved me huge amounts of time. 

Before you start importing things:

• Plan your space structure before you move things in. 

It's pretty annoying having a structure set up and working only to find it doesn't scale to accommodate what you're transferring and you have to move things around again.  This is where a content person is really helpful if you're a technical person.  Content people are good at the structure and layout of large bodies of information, and we'll help you analyse the user needs and get it right.  Confluence's space and page structure is deceptively simple because this simplicity means it's very easy to create monolithic spaces with one massive list of alphabetically ordered pages.  But people don't connect information alphabetically, so creating a space directory, page trees and label taxonomy using the guiding principles of good information architecture will make it much easier for people to navigate.

• If multiple people are bringing stuff in, agree on common naming conventions, page structure, and labels.

There's no getting away from the fact that if a team of technical communicators will all have slightly different ideas about conventions and structures, then a motley crew of various resources will all have very different ideas about conventions and structures.  Even if all the people importing are technical communicators, and especially if they're not, set agreed standards for page naming conventions, page structure and labels BEFORE anyone imports anything.  Otherwise it'll require a massive remedial exercise later on to standardise everything, or if this isn't done, your Confluence instance will be a mess.

• On the subject of labels, use them to say where a Confluence page came from, e.g. wiki name, shared drive, SharePoint, or wherever.

If you've never gone through this kind of process before this might seem superfluous, but believe me, it's not.  No matter how careful you are when you're importing, you or someone else will want to check the original source because "it doesn't look right" or "I'm sure we used to have more information on this in the old system".

And while we're talking about it:

• Keep your old repositories for at least 6 months, just in case. 

Transfer them to a portable hard drive that an admin locks in a secure cupboard if necessary, but don't "move and delete" because you'll regret it (even if no-one needs the back up you'll always be fretting that someone will need the back up).  If after 6 months (or whatever time frame you're comfortable with) you haven't needed the back up, get rid of it.  But in the meantime, keep them so that you can answer queries about "it doesn't look right" or "I'm sure we used to have more information on this in the old system" (see above) and so that you can do "idiot checks" to make sure you've got everything.  Pro tip: Every time you import something, move the original to a new location that mirrors the structure of the original location.  That way you can be sure everything's been imported.  If you can't realistically move it, mark it with (something like) an underscore at the beginning of the title.  This is also helpful when multiple people are importing things as it stops people importing the same thing twice.

Despite the fact that you're keeping your old repositories for a while:

• Bring as much metadata over as possible, especially who last edited [whatever you're importing] and when.

When you create a page in Confluence, your name is sat under the title as the creator.  This isn't useful for people who want to ask questions of whoever created the original content.  Pull the metadata from wikis or documents (manually if necessary) and add it to the page, preferably in a default location such as just under the title. 

Having said that:

• Consider adding smaller documents as attachments rather than extracting the contents. 

This will greatly reduce your import time and allow you to turn off your old system much quicker.  You can then turn the attachments into actually pages over time if you want to.  I wouldn't advocate using Confluence as a document library because really it's very poor at that.  But in terms of speed, you can drag and drop multiple documents at once into the Attachments page (or the Attachments macro) and if you're pushed for time to remove things from the old system this will work as a temporary measure.

Finally, a couple of "human" issues:

• Manually porting things over can be boring and a lot of people won't do it right because of this.  Only get people who really enjoy doing this kind of repetitive, finicky work, otherwise you'll spend huge amounts of time correcting the work of people who got bored 10 minutes after they started.
• As soon as you can turn off the old systems, do it.  Or at least restrict access to them.  People are creatures of habit and lots of them will keep using the old systems until it's literally not possible,
• It's going to take longer than you thought.  Take a deep breath, settle in for the long haul and don't get downhearted.  You can and will do this, and it can and will be a success.

The 5 Reasons Developers Don't Like Writing Documentation

A popular gripe amongst technical writers is that a lot of developers don't like writing documentation.  In fact, a small cottage industry of tool makers has sprung up specifically to help companies get developers to provide some form of documentation by making the process as easy and coding-like as possible.  If you've used tools like OpenAPI (formally Swagger), JavaDocs or Jekyll then you'll be familiar with this kind of tool.  The aim of this cottage industry is to make writing documentation as much like writing code as possible, which means allowing users to focus as much as possible on the syntax and not the semantics.

These tools are all very useful, but whilst they may be efficient ways of creating certain types of documentation, they treat the symptom and not the cause.  A lot of (most?) developers don't like writing documentation.  Why not?

Having worked with my fair share of developers over the years, I've seen and heard many answers to that question, but they all reduce down to one of the 5 following reasons:

1. It's boring
2. It's difficult
3. It's messy
4. It's dangerous
5. It's unmanly
   

Let's unpack these a bit.  I'm going to refer to "developers" below, and by that I mean "the developers who would say that this is one of the reasons they don't like writing documentation".

1. It's boring

Of all the reasons, this is the most obvious and overarching.  Developers find writing documentation to be a boring task.  Perhaps a more accurate word would be uninteresting, because writing documentation is not an interesting task.  If you don't find explaining and teaching interesting, if you have no interest in understanding the mental perspective of a target audience, if you think formatting and writing styles are dull or unimportant, then writing documentation is not going to grab your attention.

2. It's difficult

This is equally as obvious, but a lot less admitted because people don't like to admit they can't do something.  This is especially true for that sub-set of developers who think that documentation is unmanly (see below) or who generally pity and/or mock non-developers as being somehow less intelligent than developers.  If you've worked in software for any length of time you'll know exactly the type of developer I mean.  The fact remains that many developers simply lack the writing skills to write documentation well, or if they have the basic skills they don't have the confidence to use them for fear of looking stupid.  In fairness that's not an attitude specific to developers; lots of people don't try to do things because they're scared of looking stupid, but if you've ever mocked someone, even gently, for being "just" a technical writer, you're probably not looking forward to a chance to demonstrate that you can't even remotely do their job.  Better to sneer than look dumb.

3. It's messy

A big part of the reason that documentation is difficult is that natural language is organic and messy and often follows illogical rules.  Developers have spent their careers, and often many years before, learning how to use languages that are clean, designed and above all logical.  Developers only have to worry about syntax, but semantics?  No.  No, no no.  Semantics can often seem to preclude right and wrong, so for a developer who's used to the binary test of "compile/doesn't compile" or "passes unit test/doesn't pass unit test", writing in natural language for others to critique without having any real sense of what's correct and what's incorrect is a deeply terrifying thought.  The fact that only the very best and brightest end up working on natural language processing at the companies that are any good at it just solidifies the notion that writing in natural language is a one-way ticket to looking stupid unless you're brilliant at it.

4. It's dangerous

Not in the sense of physical danger (especially since everything's electronic now and you no longer have to worry about paper cuts or dropping a heavy manual on your foot - shout out to my old-school veterans!), but more in the sense that once you've written documentation people will a) associate you with that documentation and possibly product, and b) people might actually want you to write more documentation, possibly even on other bits of code.  Worse case scenario: People see you as someone who can write documentation so you'll have to do a lot more of it.  There are plenty of developers who would genuinely consider jumping out of the window rather than be the developer that people go to for documentation.  Writing documentation can lead to writing more documentation, and very soon that can lead to having a reputation for writing documentation.  This is not good, so it's best to be very bad at it or very awkward to get any documentation from.

5. It's unmanly

Correctly or incorrectly there is an attitude amongst some developers that writing documentation is not a manly occupation.  For those people that aren't developers this might seem at first sight to be a completely bizarre attitude, but whilst I think it's wrong, it's also not an attitude that comes out of nowhere.  For a start, men are vastly overrepresented in development (I don't need to link to the stats on this; Google will find you a large number very quickly) and women are vastly overrepresented in technical writing (refer to this article as an example of the trends in writing).  Whether this is cause or effect can be debated ad nauseam, but the point is that developers are much more likely to have worked with female technical writers and male developers.  The second reason is that technical writing requires a person to collaborate, think about the needs of others, step into the user's shoes and above all display empathy.  This sounds similar to what are known as the "caring professions" such as nursing, and as such stereotypically seen as being more appealing to women then men.  It's the equivalent for some people of doctors and nurses; why be a nurse who has to change bandages, empty colostomy bags and give bed baths when you could be a doctor who gets to analyse, diagnose and fix people, maybe even save a life.  And notice that a nurse "has to" whereas a doctor "gets to".  There is an alpha-male competitiveness to many developers, and that doesn't fit well with putting the needs of other people first. 

Entirely anecdotally, I've found that the female developers I've worked with over the years generally have no problem writing documentation, and the ones that do only have a problem because other (male) developers sometimes see writing documentation almost as a sign of weakness.  In some development teams writing the documentation can have almost as much of a gender bias as the old school "women make the tea" attitude, so female developers in that scenario would rather not write documentation as it will pander to the idea that they're not "technical" enough like a "real" developer.  Conversely, if I think of the 20 most vociferously anti-documentation developers I've met, they've all been alpha-male types.  Correlation is not causation, and all that, but I do find it a very interesting concurrency.


Every reason I've ever seen or heard for developers not writing documentation can be reduced to one of these 5 reasons.  I don't want to tar all developers with the same brush; many developers write documentation happily, and many of those do a great job.  Equally, I don't want to accuse all developers who don't like writing documentation as thinking that it's unmanly; I suspect this is a minority view that will only become rarer in the years to come.  If you think I've missed a principle reason or you've got an opinion on which reason is the biggest prevent of developers writing documentation, add something to the comment below.

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.

TCUK16 Awards

The ISTC held their annual Technical Communication UK Conference at the Wyboston Lakes Executive Centre, Cambridgeshire, from September 13 - 15 this year.  I attended the gala dinner on the evening of the 14th, and whilst I was there the UK Technical Communication Awards winners for 2016 were announced.

I'm honoured and (genuinely) humbled to say that the ISTC have seen fit to award me the 2016 Best Procedural Communication award for the How to Scale Documentation series that I recently wrote on this very blog:

The judges remarks were:

"Really well organised with appropriate and consistent details. The structure aids readability. Great typography choices, used to enhance the content, and to visually chunk information. Great use of space and colour in titles. The entry’s distinct conversational style works extremely well with the chosen subject and audience.

This entry is so effective because it makes everything seem so manageable. The user is guided through the series of articles and can be confident of finding explanations and at the right level."

To say that I was surprised when the ISTC told me I'd won would be a huge understatement.  Up until that point my entire trophy collection consisted of a bronze medal in a judo competition when I was 16 and a plastic cup as a member of a league and cup double winning cribbage team when I was 18.  I didn't need a trophy cabinet so much as a trophy shoebox.  Now I've got a very handsome (and heavy) glass trophy that's got pride of place on the bookshelf in my office.  To say I'm happy doesn't begin to describe it.

Congratulations to all of the winners, especially Peter Anghelides as the winner of the Horace Hockley Award for Outstanding Contribution to the Profession.  You'll be able to see a list of all the winners and read the winning entries in December's issue of Communicator.  Also, my personal thanks go, in no particular order, to:

• Elaine Cole, for guiding me through the evening with courtesy and commendable patience, as well as for putting me at ease before I had to go on stage in front of a room full of more or less sober peers to collect my award;
• Alison Peck, for making a conference debutant feel so welcome by chatting to me all through dinner, despite everyone in the room wanting to talk to her;
• Galyna Key, who couldn't attend the conference this year, but does such a wonderful job organising, promoting and running the UKTC awards.

And to everyone else I met at the Conference this year, thank you for making me feel so welcome.  It was a pleasure to meet so many dedicated, passionate and skilled technical communicators.  I hope to see you all next year!

Are Technical Writers Becoming Obsolete?

When I started working in the software industry just after the turn of the century, there were Technical Writers, Document Authors and occasionally - just to spice things up a bit - Technical Authors.  All 3 of these roles did the same thing: write end user documentation that would either be printed or displayed on screen in a help format like CHM.  This documentation was aimed either at people who installed, configured and administered the software, or at users who had to navigate the UI on a daily basis to do their job.

Nowadays, every part of that has changed.  We have Information Architects, Knowledge Engineers, Content Strategists, UX Writers and "Document Wranglers" (no, me neither).  All of these roles seem to do different things, and none of them seem to have writing good old-fashioned help documentation as their primary role.  End user documentation seems to have become very passée, with little love left for a large body of writing that explains how something works. The notion of putting documentation into a .chm is scoffed at; the notion of providing a printed copy is as old-fashioned as the idea of burning your DevOps maven because she might be a witch.

Some of these changes are driven by technology.  With many applications being solely or largely online, it makes no sense to provide a .chm when a .chm is essentially just HTML, CSS and JavaScript.  There's a better, faster, more open delivery mechanism for that, and it's called a web page. On that note, as dial-up has gone the way of the phone box, there's no need to send customers the help file on a CD or on actual paper through the post.  People can download a 500 page 10mb document in a couple of seconds, although the irony is that as the documentation is delivered online using topic-based authoring, they can pick and choose what they want to see so they'd never need the whole documentation stack anyway. 

Likewise, the explosion of mobile apps and the sudden realisation that yes, good UX design IS ACTUALLY IMPORTANT (a fact that many, many companies seem to have been oblivious to pre-smart phone) has meant that a lot of small companies are letting their design do the communication for them, and the absolute minimal documentation required is in the form of prompts, labels and warnings.  These are done, if anyone does them formally, by the UX designer or a dev who's more interested or more junior than the other devs.  The mobile apps created by big companies have also forced them to realise the importance and value of good UX design, but unfortunately the completely expected has then happened: "Ooh, we didn't need a technical writer for our new mobile app because of the great design.  Let's apply that principle to our enterprise application and we can save on writers!" (This is despite the fact that their 20-million-lines-of-code enterprise application is lugging around years of technical debt and is so poorly designed that the idea of making it lightweight enough to go online is a running joke amongst the devs.  But sure, get rid of your writers, that's the problem you need to solve.)

And some of these changes have come about because it's now easier to automate some of the writer's job.  If you set up Swagger with the right templates and show a little care, your API documentation, or at least the core of it, can be provided at the press of a button.  Provide your Confluence users with well-thought out templates with mandatory fields and macros linked to JIRA, and your release documentation can be written by anyone in your team.  I would never say that these thing are enough (and I'll believe that to my dying day) but the cost-benefit ratio of hiring a dedicated writer changes with each new automation technology that chips away at the periphery of what the writer does.

However, some of these changes to the writer function are driven by methodology.  In an agile world - and if you're not agile you're very out-of-step with modernity, no matter what you think about it - the specialist is a dying and unwanted breed. No-one can be "just" a writer any more, because what we do often doesn't exist in any meaningful way now. Sure, there are plenty of massive enterprise level applications out there that need equally massive help files, but these are becoming the exception rather than the rule.  This is not helped by disruption on a grand scale from start-ups that value doing one thing really well, and a clientele of millennials who are starting to reach an age where they an have an input into buying decisions, and who are not bothered in the slightest by the idea of buying 10 different apps and using IFTTT to fit them together, rather than spending 20x as much on a behemoth from a 50 years old blue chip. 

With everyone moving to agile, the expectation is that the specialist writer can no longer be siloed into "just" writing documentation.  Hence a role like Knowledge Engineer, where you conduct the fragmentary topics to the right place to form a coherent orchestra for your audience, or Content Strategist, where you act as a lode stone to keep all of the disparate documents from different experts pointing in the same direction.  In many cases it is no longer enough to be able to write; you must be able to plan, build, guide, persuade, manage.  Writing in and of itself is almost secondary.

If you look at the coalescing of the following trends:

• Mobile apps;
• Better UX investment;
• More documentation automation tools;
• Fragmented market of smaller providers;
• Move to "specialised generalists" in agile.
  

Then you'll see that none of them are positive for the working prospects of a "pure" technical writer. It may seem that the pure skill of a technical writer - writing - is less valued than it was before, but the companies that valued this before will still value it now.  It's the changing of the technologies and methodologies that are allowing companies that never really valued documentation to do away with technical writers, and new companies that join the fray don't see the cost-benefit ratio of having a technical writer in the first place.  They hire a Content Strategist to provide a guiding strategy and write some templates, add documentation (using Swagger and other tools) to the Definition of Done, and have a Knowledge Manager to look after the internal wiki and provide light editing of the docs.  They release updates several times a week so there's plenty of scope to iteratively improve the docs as they go.  And that's it.  Where does the technical writer fit into that?  Answer: They don't.  


So where do you go if you're a technical writer?  Do you transition to analysis, QA, testing, product management, training, support, or move to a different industry altogether?  Do you keep chasing the ever-decreasing number of "pure" technical writing jobs?  Do you specialise in API and/or SDK documentation on the basis that it's one of the few areas where there aren't enough qualified writers to fill the all the vacancies?  All of these are valid and sensible options.  In the long run though, you're best off learning how to do all of the things that have been chipped away.  Learn how to use Swagger and other documentation automation tools.  Learn how text is displayed in your application and become its writer, editor and proofreader.  Learn at least the basics of UX design and join the discussions about how best to show - rather than tell - the user what to do next (because no-one is better than you at understanding that).  Become a moderator for forums that discuss your company and its products.  Learn how to manage the knowledge assets your company has.  Learn what a content strategy is and create one.  

Because being a Technical Writer is no longer enough in a lot of companies.  Eventually it won't be enough in any company. 

To Be a Good Agilist, You Need To Be a Modern Renaissance Man

During the Renaissance in Western Europe, a certain type of man came to the fore as the exemplar of what a person should be.  Whereas in the Middle Ages preceding the Renaissance a man might be a craftsman, an artist, a priest or a soldier, the Renaissance saw the birth of men who could be all these things, and more. It was not enough to be an orator, a soldier, a poet, a scholar.  A man - and it was always men - had to speak several languages fluently, be a fine horseman, write epic poetry, lead soldiers, demonstrate athletic prowess and, of course, be able to woo a lady.  Nowadays the requirements might be different (and women are no longer excluded from the education needed to be a polymath), but the intent remains the same:

"A human being should be able to change a diaper, plan an invasion, butcher a hog, conn a ship, design a building, write a sonnet, balance accounts, build a wall, set a bone, comfort the dying, take orders, give orders, cooperate, act alone, solve equations, analyze a new problem, pitch manure, program a computer, cook a tasty meal, fight efficiently, and die gallantly. Specialization is for insects." (Robert Heinlein)

Or to put it more bluntly:

"Single-mindedness is all very well in cows or baboons; in an animal claiming to belong to the same species as Shakespeare it is simply disgraceful." (Aldous Huxley)

What was it about the Renaissance that created men such as da Vinci, Michelangelo and Galileo?  The printing press created a relative explosion in the availability of the printed word, and with it the lifeblood of learning: knowledge.  The influx of Islamic learning (which also reintroduced a lot of Ancient Greek and Roman scholarship that had been preserved by Arabic scholars whilst the Europeans were busily destroying anything "heretical" during the Dark Ages) gave new ideas and avenues of exploration.  The Church, which over the preceding centuries had become dogmatic and corrupt, was (slowly) losing its authority both spiritual and temporal; in the middle of the Renaissance Martin Luther wrote his 95 theses about the corruption of Church indulgences and began a process that would cleave the Roman Catholic Church in two.  These events came together to provide an environment where not only was it becoming easier to find knowledge to learn from, but the overwhelming authority of the day was losing it's ability and authority to prevent people challenging the prevailing dogma.  People could start to challenge the orthodoxy of how the world worked rather than having to be content with a religious explanation that had undertones of disapproval for your temerity in even asking the question.

It's said that da Vinci was the last man to know everything that could be known (although many others have jostled for this title), partly as a sign of his brilliance, but also as a sign of how much more there is to know nowadays.  And that body of knowledge is expanding exponentially; whilst for da Vinci there was philosophy (the "natural sciences"), mathematics and art to master, for the modern human it would take a lifetime to become merely conversant with every branch of engineering, let alone a master of them.  And then there is mathematics, physics, chemistry, biology, astronomy, psychology and so on and so on, and knowledge and understanding in all of these fields is increasing every day.

But the spirit of intense curiosity that drove the Renaissance men is no more abated today than it was then.  And like the Renaissance men we are living in a time when knowledge and learning is undergoing an explosion of democratisation and availability, except this time it's the electronically printed word delivered through the internet rather than ink on a pig skin or dried wood pulp.  We may no longer have the capacity to know the full corpus of human knowledge, but we can choose to learn anything that we wish, largely for free, from the comfort of our homes.

I've made the point before that the unicorn at the heart of scrum is the multi-functional team: very desirable but largely mythical. It's largely mythical for the simple reason that it's too difficult for a person to become a master of analysis and development and testing and documentation.  It's not difficult because each of the individual elements is too difficult, but because they are all different skills with different pre-requisites and ever-increasing bodies of knowledge that you need to stay on top of to maintain your mastery.  There simply aren't enough hours in the day, assuming you have some form of personal life (and would like, in no particular order, food, recreation, relationships and sleep). I stand by this, whilst accepting that there are a few people who can master 2 of these concurrently, and very, very occasionally 3 or more.  For us mere mortals though, it's unrealistic to expect to be a 10x or full-stack developer whilst also having an encyclopedic knowledge of BABOK.

Nonetheless, that insatiable curiosity and thirst for learning that drove the Renaissance men to heights of mastery can and should be an inspiration to show that it is possible to have great knowledge in diverse areas.  There is much overlap between the functions of each profession that makes up a scrum team; if da Vinci can be both a master anatomist and the inventor of the helicopter, is it beyond the bounds of reason that a single person could be both a master of documentation AND a competent tester, or a mistress of development AND a competent analyst, or any other combination of professions in your team?  At the very least a database developer should also know the basics of web development; a technical writer should be able to write both API documentation and a Beginner's Guide and so on.

The march of the specialist has benefits for efficiency and productivity, but only the generalists can create things in a non-linear (non-conveyor belt) fashion, only generalists can see the bigger picture, anticipate how their work will affect others in their team and create and innovate within that team.  Without expecting people to master multiple professions, there is still scope for learning things that other professions do every day, even if mastery is beyond you.  

As with the Renaissance men it is no longer acceptable to say "I don't do that, I'm a developer/tester/analyst/technical writer." You can, should and must be more.

You Need an Agile Attitude, Not Just Agile Behaviours

In one sense it's easy to move to an agile way of doing things.  You send your people on some training, start using sprints, change your Product Managers to Product Owners, maybe hire a consultant to spend some time advising your staff, and you're agile, right?

Wrong.

There are 2 big issues with that description:

1. You can't force long-term behavioural change;
2. There is no "agile way of doing things".

And yet that description of how companies change to agile is accurate in a large number of organisations.  Sure, the details may be slightly different and there are differing levels of commitment and intent, but in general the notion of changing procedures to "do things in an agile way" is a very common way of moving from [whatever went before] to "agile".  The key error in this situation is that what needs to be changed is not behaviours as such, but attitudes.

It's true that behaviours do need to change when you move to an agile methodology, because, for example in the case of Scrum, you've got new roles of Product Owner and Scrum Master, new ceremonies for planning, review, retrospective, grooming and daily scrums, and new artefacts to interact with like a backlog and user stories.  The daily and weekly routines that people are used to will change, as will the release cadence, and different behaviours are needed to deal with these.  But these behaviours cannot be forced onto people as an act of managerial diktat.

Everyone involved in an agile transformation must understand that the paradigm you used to work in is not the paradigm you'll be working in from now on. The biggest intellectual challenge when moving to a new paradigm is not a new way of doing things, it's a new way of thinking. Moving to an agile methodology is exactly the kind of paradigm shift that requires a new way of thinking, and make no mistake: it's hard. 

The classic example of a paradigm shift is the the switch from the Ptolemaic (Earth-centric) model of the planets to the heliocentric (Sun-central) model, also known as the Copernican Revolution.  Without wishing to stretch a point too much (because the move from [whatever you were doing before] to an agile methodology is not on the same level as a true paradigm shift like the Copernican Revolution) one of the key problems with a paradigm shift is that you can't compare things between 2 paradigms because they are incommensurable, that is "not-comparable".  Now, there is significant debate on how much this incommensurability is true, but in at least some senses you can't compare the claims of one paradigm with those of another because assumptions and boundaries are used to make judgements within a paradigm, and the assumptions and boundaries of 2 paradigms can be radically different.

Therefore it's not the case that you can simply map agile things on to what you did before.  The new roles are not "more management".  The new ceremonies are not "more meetings".  The new artefacts are not "more bureaucracy".  They are not these things because in an agile methodology the roles, ceremonies and artefacts are there for the very purpose of removing unnecessary management, meetings and bureaucracy.  You use these roles, ceremonies and artefacts to keep management, meetings and bureaucracy to the bare minimum needed to make the vital decisions - prioritisation, estimation, commitment - and convey the vital information between the team members, and between the team and the business.

Telling people to engage in these behaviours - to "do things in an agile way" - will only lead to a begrudging change of process, not a change to an agile paradigm.  To achieve that paradigm shift you need to change people's attitudes, because behaviours only become routine and accepted if they flow naturally from an attitude.  Think of agile not as a series of actions, but as a field in which those actions take place.  Place an object of mass in a gravitational field, and it will act in accordance with the laws that govern that field.  This is an analogy that can't be stretched too far for all sorts of reasons, but the general point holds: People act in accordance with the (cultural) field in which they find themselves, which has the practical effect of instilling an attitude in them. They will continue to act in that way until they are placed in another (cultural) field that forces them to modify their attitude. 

There is a plethora of information available about how people's behaviours are influenced by the cultural and social attitudes in which they find themselves, so we won't cover any of that here.  But trust me when I say that a person's behaviour is determined far more by the behaviour of the people around them, especially people in a position of influence or power, than a lot of those people would like to admit.  This means that the most effective way for an organisation to successfully transition to an agile methodology is for leaders and influential people to display the attitudes that will cause others to follow them.  It is a top-down process, but through example, not through mandate.  If you consider the nature of virtue, it's easy to perform virtuous acts but difficult to be virtuous.  Anyone can perform a virtuous act, such as giving to charity, but that is not the same thing as being virtuous.  It is the same with agile.  Anyone can perform an agile action, such as holding a sprint retrospective, but that is not the same thing as being agile.  

It's not about an "agile way of doing things", it's about an agile way of seeing what's in front of you and acting accordingly. 

How to Spot an Office Saboteur, According to the CIA

The Strategic Services Unit - an American intelligence agency that was folded into the nascent CIA after World War II -  produced a number of field manuals, as these kind of organisations are prone to do.  One of them, Field Manual no. 3, deals with what's called "Simple Sabotage", a way for "citizen-saboteurs" to damage the war effort of an enemy without having to blow up bridges, demolish railway tunnels, or perform any of the commando-style activities that make for a great rainy Sunday afternoon film.

There's plenty of interesting stuff about how to damage, disable, and otherwise ruin machinery of various kinds, how to set fires, how to sabotage fuel, and generally annoy the mechanical industrial efforts of an enemy.  I've linked to a declassified PDF of the manual above if you're interested in that sort of thing, but I'm going to focus on what the manual describes as the second type of simple sabotage, which:

.....requires no destructive tools whatsoever and produces physical damage, if any, by highly indirect means. It is based on universal opportunities to make faulty decisions, to adopt a non-cooperative attitude, and to induce others to follow suit. Making a faulty decision may be simply a matter of placing tools in one spot instead of another.  A non-cooperative attitude may involve nothing more than creating an unpleasant situation among one's fellow workers, engaging in bickerings, or displaying surliness and stupidity.

This type of activity, sometimes referred to as the "human clement," is frequently responsible for accidents, delays, and general obstruction even under normal conditions. The potential saboteur should discover what types of decisions and non-cooperation are normally routine in his kind of work and should then devise his sabotage so as to enlarge that "margin for error."

This type of sabotage focuses on getting people, rather than machinery, to run inefficiently and slowly. What's telling is that 70+ years ago the kinds of behaviours described were well-understood as being destructive, damaging and otherwise antithetical to a well-run, productive office, and yet you still find people engaging in these behaviours well into the 21st century.

The PDF is a scanned version of a type-written 20 page manual, and it can be a bit hard to read at points, so I've transcribed the relevant sections below (having removed a few that refer to dealing with the Gestapo because it's 2016).  So without further ado, let's see if anyone you know is an office saboteur, according to the CIA:


(11) General Interference with Organizations and "Production

  (a) Organizations and Conferences

1. Insist on doing everything through "channels." Never permit short-cuts to be taken in order to expedite decisions.
2. Make "speeches," Talk as frequently as possible and at great length., Illustrate your "points" by long anecdotes and accounts of personal experiences. Never hesitate to make a few appropriate "patriotic" comments.
3. When possible, refer all matters to committees, for "further study and consideration." Attempt to make the committees as large as possible - never less than five.
4. Bring up irrelevant issues as frequently as possible.
5. Haggle over precise wordings of communications, minutes, resolutions.
6. Refer back to matters decided upon at the last meeting and attempt to re-open the question of the advisability of that decision,
7. Advocate "caution." Be "reasonable" and urge your fellow-conferees to be "reasonable" and avoid haste which might result in embarrassments or difficulties later on.
8. Be worried about the propriety any decision - raise the question of whether such action as is contemplated lies within the jurisdiction of the group or whether it might conflict with the policy of some higher echelon.

 (b) Managers and Supervisors

1. Demand written orders.
2. "Misunderstand" orders. Ask endless questions or engage in long correspondence about such orders. Quibble over them when you can.
3. Do everything possible to delay the delivery of orders. Even though parts of an order may be ready beforehand, don't deliver it until it is completely ready.
4. Don't order new working' materials until your current stocks have been virtually exhausted, so that  the slightest delay in filling your order will mean a shutdown.
5. Order high-quality materials which are hard to get. If you don't get them argue about
   it. Warn that inferior materials will mean inferior work.
6. In making work assignments, always sign out the unimportant jobs first. See that the important jobs are assigned to inefficient workers of poor machines.
7. Insist on perfect work in relatively unimportant products; send back for refinishing those which have the least flaw. Approve other defective parts whose flaws are not visible to the naked eye.
8. Make mistakes in routing so that parts and materials will be sent to the wrong place in the plant.
9. When training new workers, give incomplete or misleading instructions.
10. To lower morale and with it, production, be pleasant to inefficient workers; give them undeserved promotions. Discriminate against efficient workers; complain unjustly about their work.
11. Hold conferences when there is more critical work to be done. 
12. Multiply paper work in plausible ways. Start duplicate files. 
13. Multiply the procedures and clearances involved in issuing instructions, pay checks, and so on. See that three people have to approve everything where one would do. 
14. Apply all regulations to the last letter.

(c) Office Workers

1. Make mistakes in quantities of material when you' are copying orders. Confuse similar names. Use wrong addresses.
2. Prolong correspondence with government bureaus.
3. Misfile essential documents.
4. In making carbon copies, make one too few, so that an extra copying job will have to be done.
5. Tell important callers the boss is busy or talking on another telephone.
6. Hold up mail until the next collection.
7. Spread disturbing rumours that sound like inside dope.

(d) Employees

1. Work slowly. Think out ways to increase the number of movements necessary on your job: use a light hammer instead of a heavy one, try to make a small wrench do when a big one is necessary, use little force where considerable force is needed, and so on.
2. Contrive as many interruptions to your work as you can: when changing the material on which you are working, as you would on a lathe or punch, take needless time to do it. If you are cutting, shaping or doing other measured work, measure dimensions twice as often as you need to. When you go to the lavatory, spend a longer time there than is necessary. Forget tools so that you will have to go back after them.
3. Even it you understand the language, pretend not to understand instructions in a foreign tongue.
4. Pretend that instructions are hard to understand, and ask to have them repeated more than once. Or pretend that you are particularly anxious to do your work, and pester the foreman with unnecessary questions.
5. Do your. work poorly and blame it on bad tools, machinery, or equipment. Complain that these things are preventing you from doing your job right.
6. Never pass on your skill and experience to a new or less skilful worker.
7. Snarl up administration in every possible way. Fill out forms illegibly so, that they will have to be done over; make mistakes or omit requested information in forms.
8. If possible, join or help organize a group for presenting employee problems to the management. See that the procedures adopted are as inconvenient as possible for the management, involving the presence of a large number of employees at each presentation, entailing more than one meeting for each grievance, bringing up problems which are largely imaginary, and so on.
9. Misroute materials.
10. Mix good parts with unusable scrap and rejected parts.

(12) General Devices for Lowering Morale and Creating Confusion 

1. Give lengthy and incomprehensible explanations when questioned.
2. Report imaginary danger
3. Act stupid.
4. Be as irritable and, quarrelsome as possible without getting yourself into trouble
5. Misunderstand all sorts of regulations concerning such matters as rationing, transportation,
6. traffic regulations.
7. Complain against ersatz materials.
8. Cry and sob hysterically at every occasion, especially when confronted by government clerks.

 
So there we are, office sabotage 101. There are a grand total of 47 possibilities there, and by my reckoning I've seen people do at least 22 of them.  Can anyone out there beat that score?  

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.