Sunday 24 July 2016

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.


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.

Sunday 10 July 2016

The Basics - How to Document a Script

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

You work on a project that involves making database changes using SQL scripts.  Your customers' DBAs need to know what the scripts will do before they run them.  This article covers what you typically need to include in your script documentation.

Before documenting any scripts, make sure you include a warning to your customers to back up their database before running any scripts.  Ideally, customers should test the scripts on a test version before applying them to live.

1 - What Database type and version is the script designed for?

Does the script update MSSQL? Oracle? MongoDB? Something else?  What versions can the script be run on? Are there scripts that do the same thing for different database types and versions?

For example:

This script is designed for Oracle 10g and later.  You can find the equivalent Mongo script here [where "here" is a hyperlink to the Mongo script location].

2 - Do you need any particular permission level or security settings to run the script?

Do you have to have a specific system or object privilege?  What user roles should run this script?  Is the script likely to impact high-security areas such as users, passwords, personal details, company accounts, and so on?

For example:

This script requires the SELECT ANY TABLE privilege.  We recommend that a SYSBDA review the script before running as it will add a constraint to the main USER table.

3 - Which database or schema does it need to be run against?

If your application(s) provide more than one database (separate finance and personnel databases, for example), make it clear which database the script needs to be run against. Provide a warning about running the script against any but the intended database.

For example:

This script applies to the Finance database/schema only.  Do not run it against any other databases as there may be unintended consequences up to and including data loss.

4 - What does the script do at high level?

Explain how the script amends the structure or the content of the database.  The primary types of change are:

  • Add/delete/amend table(es)
  • Add/delete/amend column(s)
  • Add/delete/amend index(es)
  • Add/delete/amend constraint(s)
  • Add/delete/amend data
For example:

This script will insert 3 new columns to the User table and populate the existing rows with default data.

5 - What does the script do in detail?

Provide all available information about the detail of the script.  This will depend on the type of script, but for adding or amending tables or columns include the following:

  • Friendly name
  • SQL name
  • Primary keys
  • Foreign keys
  • Nullable
  • Data types
  • Data lengths
Explain why something is being added/amended/deleted, and ideally link to the release notes for the code change that the database change is required for.  If data is being deleted explain why it isn't needed any more; flag up data deletion strongly so that customers can make an informed decision about running the script with full knowledge of what will happen when they do.

There are so many possible combinations that examples would be impractical here. Focus on putting the data into a readable format such as a table.  This will also help you make sure that the information provided is consistent.

6 - How will this affect reporting and/or database diagrams?

Provide an updated entity relationship diagram and/or data dictionary.  Explain that cusomters will need to amend any database reports - e.g. SRS, Oracle, Crystal, etc - and explain what they'll need to change.  This is especially important for columns changes; new tables won't affect existing reports and index/constraint changes will rarely have any impact either. If a table or column has been deleted and replaced with something else, explain the mapping of the data between the old and new structure.

For example:

The new data dictionary can be found on our website here [provide link].  If you have reports that reference the deleted column, please amend them to refer to [new tablename.columnname] instead. 

These should cover all of the generic bases for script documentation.  Create templates for the types of scripts you need to document, including any bespoke requirements that aren't covered here, and you're good to go!  If you think there's something missing from the list, drop me a comment below and I'll add it in.

UK Tech Comm Awards - Nominate Yourself!

For my UK readers: The UK branch of the ISTC is looking for nominations for the 2016 UK Technical Communications Awards.

There's more information at the link above, but these 2 paragraphs should give you the gist:

"The UK Technical Communication Awards are open to any individual or team, whether employed, self-employed, contracting, volunteering, permanent, temporary, full-time or part-time.  You do NOT have to be a member of the ISTC to nominate someone, and the nominee doesn’t have to be to a member of the ISTC either.  You can nominate yourself if you wish; the judges’ decisions will be made solely on the merits of the entries, not on who nominated the entries.

We encourage entries of product/process documentation and technical innovation – the “traditional” entries – as well as entries such as blog posts, books, training material, e-learning and anything that displays, encourages or helps the production of high-quality technical communication.
There are some rules to follow, so take a quick look at them before you start nominating.  Check out the 9 categories that will be awarded and to nominate someone, or to nominate yourself, go here.  Go on, you and your team deserve it!"

I'll echo the last 2 lines - technical communicators don't always get the credit they deserve, and these awards are a great way of showing off your achievements.  I know it's not the British way, but it is genuinely OK to nominate yourself!  No-one cares as much about your documentation as you do, and if anyone deserves an award it's the unsung heroes like you who do so much to make life easier for your users.

If you've got any questions you can fill in the form here and the ISTC Awards team will get back to you very quickly.

Nominations close on July 15th 2016 - 5 days from the date of this post - so don't delay, nominate today!

Saturday 2 July 2016

Why Do People Like Writing Documentation?

If you want to annoy a technical writer, nothing hits the spot quite like hearing "Man, I'm so glad you write the documentation! I know it's got to be done, but boy, it's soooo boring!"

The technical writer-approved responses to this are:

A) smiling through gritted teeth and then seething for the rest of the day,
B) barely-concealed sarcasm about the commentator's level of (il)literacy, or
C) physical violence. 

Personally, I veer between B and C depending on the number of witnesses and the size of the person making the comment. (Ok, B.  But I spend the rest of the day wishing I knew kung fu and imagining C.)  But why, I hear you cry?  We ARE grateful for those weird people that sit in the corner and enjoy typing! Seriously, writing documentation sucks! 

Oh. Dear. God. *imagines nunchuks*

Right, listen to me.  I like writing.  I like learning things.  I like organising my thoughts on paper.  I like helping people.  I like helping people by learning about things and then organising my thoughts on paper using the power of writing.  This is fun for me, and for my fellow writers.  You think I started this blog to make myself rich?  Are you kidding me?  I write this blog because I LIKE WRITING, and I know a bit about technical writing in an agile environment, and I wanted to help writers in similar situations by sharing my knowledge.  You see how that works?  I'm helping people by organising my thoughts on things I've learnt and writing it down for other people to read.  Just because YOU don't like writing - you big philistine - doesn't mean that everyone else doesn't like writing either.  Writing is the mark of an educated civilisation.  Writing well is the mark of an educated person.  Education is a good thing.  You hear me? A GOOD thing.

We don't become technical writers to get rich (damn you, JK Rowling), get famous (hello, Shakespeare) or get people into bed (Lord Shelly, you dog!).  Those are benefits for novelists, playwrights and poets, not those of us who help other people work out how to bypass the bad design and hurried implementation of people who are glad they don't have to write the documentation.  We live in a gift economy, where the most important thing we have is our knowledge and our skills.  Tech writers don't get paid as much as devs, but we're still fortunate enough to do better than a lot of people if we work for any decent company.  As such, being able to show people how to do something they couldn't work out for themselves is a valuable commodity because generally speaking tech people don't care for overt shows of material wealth.  What gets respect is knowledge and skills, and boy oh boy do your technical writers have those in abundance.  You just know too little about what we do to realise that sometimes.

And, while we're on the subject, writing documentation is not dorky, or nerdy, or geeky.  Well, not any more than any of the other technical professions we work with day in, day out.  For us, writing things, organising concepts, helping people, these are what get us out of bed in the morning and we won't apologise for it.  Some people like playing WarHammer, some people take pride on being able to quote every line from every episode of the original Star Trek, and some people are so obsessed about their coffee that they're happy to drink something that's been defecated by an animal.  Some people do all of those things.  The Venn diagram of these people and people who work in software development contains a lot of overlap, so just remember that next time you think a writer is a bit geeky or weird for not wanting to write code instead of natural language.

Although, to be fair, developers are definitely not alone in their bemusement of why people would want to be technical writers.  When someone asks what you do and you say that you're a technical writer, there's often an awkward silence while they try to think of something to say, and that's mainly because the stock answer of "Oh, that's interesting + [question]?" seems to get stuck in their throat.  Because not only do they not find technical writing interesting, they find it SO uninteresting that they can't even maintain the social civility of lying.  At least with a lawyer or salesman you can make a crack about their lack of morals and know they've heard it a thousand times before, even if you couldn't give a flying duck about the intricacies of their job.

Don't worry, like the weasels in notorious professions, we're also well-used to hearing a stock answer.  It's just that for technical writers that stock answer is "", and believe me, as people with both morals and a soul that we'd like to keep relatively unsullied, we're much happier with that than poorly-disguised contempt. Still, to help you, here's a few gambits that might help:

  1. "That's interesting, is your documentation in the definition of done?  That's a thorny issue at our place."
  2. "Yeah, a friend of mine does that too and she loves it!"
  3. "Man, I couldn't do that job because my English sucks.  Much respect to people who've got that talent."
  4. "Oh, so you teach people about new tech?  That's awesome!"
  5. "Really?  Wow, you know I've always thought writers were really sexy....."
Ok, maybe not #5.  But the first 4 are all good.

Anyway, having got slightly distracted, back to the issue at hand.  I like what I do.  Scratch that, I love what I do.  Learning stuff, organising that knowledge logically, writing it down for other people - that's like crack cocaine to me.  Yes, I do other things like knowledge management and training people because I'm not a pure technical writer any more, and yes, I love those aspects of my job.  But my love stems from those core desires that all technical writers have: to learn, to organise, to teach. 

That's why people like writing documentation.