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.