Saturday 28 March 2015

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

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

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

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

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

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

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

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

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

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

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

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


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

Tuesday 10 March 2015

99% Dirty Agile

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

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

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

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

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


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

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

Sunday 8 March 2015

The Basics - How To Document A Bug

An occasional series looking at best practice for common documentation tasks and situations.

Documenting a bug is a common activity for technical writers who work in production environments.  Although every company will have differing standards for documenting bugs, there are key pieces of information that should be transmitted to the customers (internal or external), regardless of your company's preferred style or terminology.

These key pieces of information are:

  • Who reported the bug?
  • What was happening before?
  • Where was it happening?
  • When was this happening?
  • Why was this wrong?
  • What's happening now?

Let's look at these items and explain why they are so important.

Who reported the bug?

Each customer will want to know whether the bugs they have reported have been fixed.  That's not to say that they won't be interested in others bugs that have been fixed, but their priority when reviewing your documentation will be to find out if the things that they think need to be fixed have indeed been fixed.  To track customer reports of bugs, most companies will use some type of ticket system.  Each call to the support desk will be assigned a ticket, and if after investigation it transpires that there is indeed a bug in the system, the development team will add a work item or task to their backlog to fix it. In agile environments these tasks will be completed in priority order; this means that a bug may not be fixed in the next release that goes out.  Therefore the ticket number that the customer has been given should be visible in the title or heading for the bug when you document it.  This will allow the customer to easily search for the bugs that they have raised with the support desk***.

What was happening before?

It's easy to say "The doohicky process is now working correctly." - and this will be an accurate reflection of reality - but that doesn't really help the customers very much.  If the reader doesn't know what the process was doing before it was fixed, they won't be able to perform their own user acceptance testing on the process to make sure that it is now working correctly (bear in mind that "correctly" may be a matter of opinion that customers don't always agree on).  It's also important that customers can check to make sure that an incorrect process hasn't amended their data; without knowing what the problem was before, their analysis will take much longer.

Where was it happening?

Not so much a problem in an app with 1 screen, but in any large application it is important to give the customer the default menu path to the location of the problem.  For example, Form A > Tab B > Grid C > Column D.  Customers want to be able to easily reproduce the conditions in which the bug was occurring, and in large systems you should tell them exactly how to get there to save them time and confusion.  It also allows them to disregard the bug fix if they don't use that part of the software.


When was it happening?

This doesn't mean "we found it last Thursday but it's been happening since the last release", which is something a developer once told me when I asked him this question. Rather, it means "at what point in the user experience did this bug occur?".  As with the Where, the When helps customers quickly reproduce the conditions in which the bug was occurring so they can test the fix. 

Why was this wrong?

For some bugs, such as the application crashing, this question is superfluous.  But where a calculation is performed incorrectly, or a process sends data to the wrong place, it might not be obvious to a person reading the documentation why this is a problem. For example, "The doohickey process was only storing data to the current and historical tables." might be an accurate explanation of the problem, but doesn't give any indication of what table(s) the process should have been storing data to.  A more complete explanation would be "The doohickey process was correctly storing data to the current and historical tables, but was not storing data to the audit table as per the specified requirement." 

What's happening now?

All of the above questions combine to form the description of the problem.  This question forms the description of the solution.  If you have entered all of the relevant information in the problem section of your documentation, the solution should be fairly simple: one or two lines stating that the problem will no longer occur (e.g. "When Save is clicked data will now be stored to all of the correct tables.") or an explanation of the change in functionality (e.g. "When the doohickey process runs, it will now include [variable x] when performing the tax calculation.").

All of this can be boiled down to: Who, What, When, Where, Why, Now, or as a mnemonic, W5N.  If you can remember to use W5N when documenting a bug, you'll always provide most if not all of the information that your customers need to see.

*** - If the bug was found internally, or doesn't have a ticket number assigned to it for any reason, either the bug is documented without a ticket number, or depending on your company's procedures, may not be documented in externally facing documentation at all (on the basis that some company's don't feel the need to tell customers about bugs that the customers didn't know about).

Good, Cheap, Quick - Pick 2

In any production endeavour you can pick 2 of the following 3 aims:


If it’s Good and Quick it won’t be Cheap.If it’s Quick and Cheap it won’t be Good.
If it’s Cheap and Good it won’t be Quick.

One of the aims of scrum is to square the Good-Quick-Cheap circle as much as possible by ensuring that the delivery of software is always Good, by de-scoping a sprint if Quick and Cheap (read: resource costs) are a concern. 

This means that in Scrum the overall solution requirements are not fixed at the start of the process but rather become a variable to be managed through the life of the project.  The 2 fixed points of Scrum are the increment delivery date - the end of each sprint - and the quality of the increment.  The de-scoping allows quality to be prioritised and the commitment from a mature team with a known velocity allows the Definition of Done to be met at the end of each sprint and thus meet the increment delivery date.  As more increments are delivered, the overall solution requirements can change as much as is necessary to meet changing customer demands.  So rather than Good-Cheap-Quick referring to the total deliverable at the end of the project, it relates to each individual sprint.

Contrast this with a Waterfall process, where the overall solution requirements are a fixed point around which quality rotates. Nominally the time to delivery is also fixed, but it might (and often does) change as technical debt is accumulated, requirements change, staffing issues arise, etc. In Waterfall the increment is the entire solution, and over that time period there are much more likely to be changes which affect the time to delivery; in Scrum, because the increment is only 2 - 4 weeks any changes which occur will only affect the next increment, not the current one.

This all means that the Good-Cheap-Quick conundrum is somewhat less of a burden in Scrum, because the ability to de-scope covers Good, the ability to re-prioritise for each sprint enables efficiency, and therefore covers to a certain extent Cheap, and the short length of the increments covers Quick.  Scrum isn't a panacea for these ills, because any methodology can be implemented poorly or inappropriately, but implemented well, and with appropriate input from those people working around but not in the scrum team (PO, BAs, Customer reps, etc), Scrum can certainly help.

As always though: Development is a process, and some things simply have to be done in order. Agile helps with that, but it doesn’t change it.  

UPDATE: Since writing this, I've discovered that the Waterfall situation that I described is actually a formal model called the Project Management Triangle (aka Triple Constraint or Iron Triangle).  On the one hand, it's a bit annoying to think I might have reinvented the wheel (yay! I've thought of something new! Oh.....hang on.....dammit....) but on the other hand it's nice to get a bit of validation that my thinking makes sense in a broader context.  Perhaps I should investigate this Project Management malarkey a bit more.....

Saturday 7 March 2015

What Skills Does a Technical Writer Need?

In terms of man-management, a manager of writers wants the same as every manager: reliability, honesty, initiative, people skills, etc.  However, there are specific hard (technical) and soft (non-technical) skills that are either required or very beneficial for a Technical Writer to have.  My career in technical documentation has been entirely focused on documenting software and the list below reflects that.  The skills listed are relatively generic, in that a specific employer may want you to have experience with a specific tool or within a particular domain, but if you can demonstrate knowledge of all of the hard skills and experience in all of the soft skills listed below, you'll stand a good chance of at least getting that interview.  

Where possible I've added a link to a good tutorial or starting point for exploration. A lot of tools allow you to download evaluation copies which you can use to familiarise yourself with them, and there are abundant CSS/HTML/XML tutorials available for free online.  Use a bit of Google power and join forums or communities if you can, and there is nothing on this list that you won't be able to get to grips with if you put the effort in. Nothing beats practical experience, especially when it comes to the soft skills, but the more you learn and are ready to put into practise, the more likely you are to succeed.

Hard Skills:

Soft Skills:

  • Organisational skills (time, email, task management);
  • Listening and questioning (for eliciting information from SMEs and developers);
  • Assertiveness (because people are busy and often don't see documentation as a priority, so you have to be assertive about your needs);
  • Desire to continually keep learning (because you need to learn new things to document them);
  • Calmness and a positive mental attitude (because development is a linear process and documentation is one of the things that necessarily gets done last, so you're often under time pressure);
  • A dry wit and a keen sense of the absurd (because coders and engineers are not like normal people, plus who wants to work with someone with no sense of humour?).

If you can master all of these you'll be a very strong candidate for a role as a Technical Writer.  However, bear this in mind: The single most valuable tool you can have is a portfolio of work.  You might learn all of the above to a level hitherto undreamt of by other technical writers.  You might know more about DITA than anyone else on the planet. what?  I can teach a monkey to use software and systems.  Anyone can learn that.  But I can't teach you to write.  You've either got it, or you haven't, and if you haven't, nothing else will make up for it.  A portfolio is the only way for me to read something you've written, and the larger and more varied it is, the better.  This doesn't mean the above skills and knowledge aren't useful, because they are, and if you haven't made an effort to learn about some of them I'd be disappointed, but I could get over that.  I can't get over an inability to write.  And the good news is that, especially if you don't have experience as a technical writer already, any writing will do.  Blog posts, marketing copy, significant comment histories on LinkedIn, academic articles, pretty much anything factual will do.  Just start writing, and be prepared to talk about it at interview (which I'll cover in a future post)!