Tuesday 30 August 2016

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. 

Sunday 21 August 2016

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.

Tuesday 2 August 2016

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?


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?