Tag Archives: value

The Joy of Peer Reviews (Part 2 – Documentation)

Posted on by
1
Reading time ~ 4 minutes

Another agile management myth to dispel – agile projects have no documentation…

The level of documentation you provide depends on the needs of your stakeholders.

About a month ago I spent some time discussing code reviews and promised a follow-up on document reviews.  Since then, the number of documents I’ve needed to work on or review has been pretty slim so there’s not been much scope for inspiration.

One of my teams are coming to the end of a major release and our product managers are re-evaluating parts of the portfolio. Both of these events drop us into some more traditional documentation areas for a while.

Before I progress, there’s three types of documentation we tend to deal with on a project.

  • Product documentation (user-facing)
  • Control documentation (mostly management-facing)
  • Technical documentation (mostly team-facing)

We produce a lot of information in all these areas but of most of it isn’t as formal documents.

Here’s the bits we treat formally…

  • Vision, business needs & minimum marketable feature set
  • High level plan (priorities, scope, cost, schedule, quality)
  • Significant, complex or high level designs (functional or technical)
  • End-user and admin guides
  • Significant scope changes (change control)
  • Closure (agreement from stakeholders that we’ve met commitments)

Before going any further. The main rule of thumb in documentation I follow is:

Strive to keep your overheads to a minimum

Focus on the level of documentation needed by the relevant stakeholders and seek alternatives where feasible. For example user guides & help files may be better replaced with automated drive-throughs, screencams and audio descriptions. Project reviews may be best served with a conversation, a single slide with some visual anchors and a sign-off.

My teams have had cases where we felt we needed more documentation because we weren’t happy with the level of traceability from our less-formal approaches.  This tends to vary depending on what levels of organizational trust exist and how much protection you may need.

Where you do need formal documentation – regardless of which of the above types it falls into here’s my basic document delivery and review guidelines…

Delivery

It’s remarkable how much good documentation is very like code.  My mantra is “deliver early and often”.

  • Start by delivering the scaffold, walking skeleton or spine of your document and get that out for initial feedback on structure.
  • Consider swarming your team around parts of the document to accelerate delivery.
  • If you have interaction across teams, ideally have the teams write their components for you – do the editorial but they cover the “meat”.
  • Balance time invested with expected value – especially before initial reviews
  • Start adding flesh to the bones one section at a time.
  • As each section is “good enough”, send it out for a draft review.
  • Following review, rework the meat and polish
  • As major themes come together for completion, review again for cohesion.

I find there’s one large challenge in writing documents – Inertia – don’t underestimate the effort needed both to get moving and to be properly finished.

Most experienced coders understand about getting into “the zone” or being in “flow”. This same situation holds true for writing documents however personally I find it’s much harder to start moving on a document, takes more sustained effort for completion and requires more polish than my code. Once you are in flow. Stopping is equally hard. Much like delivering small frequent reviewable coding tasks takes practice, so the same applies for documentation. The team approach to documentation is a great way around this once you have a scaffold in place.

Review

If producing documentation is like cutting high quality code, then it should be no surprise that reviewing documentation should be treated with similar respect.

Bear in mind, usually when you’re reviewing documentation, you’re probably at a point in the cycle where you can prevent major defects and costs in future by asking the right questions.  Reviewing documents is not a hurdle to overcome it’s an essential quality step in setting your projects up for success and in ensuring we have consensus and understanding on results.

I’ve divided the checklist into 3 parts. “Thinking”, “Approach” and “Review”.

Thinking

A few considerations to make before starting the review itself (and before submitting for review)

  • Discipline – treat this review just like you would a code peer review.
  • Should it be a document , could it be something else?
  • Who is the intended audience, is it pitched at the right level?
  • Is this technical, control or product documentation (and how does that impact our approach)?
  • Is this primarily for management, the team or our customers/users?
  • Is this document transient or permanent?
  • How critical is accuracy/precision? (compare for example to scientific or medical papers)
  • How will this document be maintained and who by?

Approach:

What form is the review going to take?

  • Round table vs offline – will the review be individuals at desktops, as a round table session or a mix of the two
  • Piecemeal or big bang – I mentioned my preference for part-deliveries. This only works if you’re willing to perform part-reviews.
  • Feedback cycle – how will you manage feedback? For large critical documents I usually forecast 2 rounds of review/rework and a total elapsed time of 2 weeks from the initial draft to completion. (that’s assuming a well-managed but not top priority review cycle). The author/coordinator should have this at the top of their stack until it’s “done done”.

Review

Points to look for – these start simple and get trickier as you go through the list.

It’s disturbing how many people only review using a subset of the top items here and get no further. Lazy reviewers may read a document without actually reading it. (Although perhaps this is a reflection that we’ve missed something in the perceived value of a document)

  • Document information and headers/footers are correct
  • Consistent formatting & numbering e.g page numbers, typefaces, sizes
  • Spelling & grammar
  • Tables of contents & figures are up to date (ctrl+a, f9, update all – in Word!)
  • Cross-references work and point to the right locations
  • Related documents or prerequisites are both accessible and necessary
  • Use of correct templates where required
  • Proper heading formatting – helps with maintenance of TOC
  • Use of change tracking and versioning
  • Identify reviewers, owners, approvers
  • _________________________________________
  • Lots of words when a picture would be better
  • Emotive descriptions (where not valid)
  • Unfounded facts and numbers (particularly sales, estimates and time lines)
  • Impacts on other teams (especially without consultation)
  • Expectations from other teams (especially without consultation)
  • Over-optimistic statements (see unfounded facts and numbers)
  • Unbounded requirements
  • Missing assumptions
  • Alternatives and rejections
  • Over-technical or not detailed enough for audience
  • Length/brevity (much like some of my posts)
  • Emotional attachment to content or single approach/ideas
  • Any prior examples of similar to compare, reference and/or improve from
  • Voice of the customer (and their future accessibility)
  • Who are the decision makers and arbitrators,
  • A clear problem statement
  • Well-defined vision
  • SMART or Elephant goals
  • What does “good”, “done” or “success” look like?
  • Quality, acceptance criteria and tolerances
  • Any disconnects between related documents or teams
  • Anything missing

Phew! – as before, I’m sure there’s more.

To summarize in one sentence…

If your documentation is important to your stakeholders, treat it with the same reverence as your production code.

Agile Is Just A Means To An End

Posted on by
2
Reading time ~ < 1 minutes

A couple of months ago I posted that software is just a means to an end.

Here’s an equally commonly lost point – in fact it’s almost identical.

Agile (or Lean, TOC, whatever) is a means, not a solution.

Our customers, users and stakeholders don’t want “agile”, they want “success”. Once they have success they’d quite like a means of making that success more repeatable but ultimately they simply want success.

We seek to promote our way of working (one of our goals as an agile community) but risk missing the actual goals of our stakeholders?

Our conversations should move away from Agile by name and onto:

  • how do we best attain our stakeholders goals?
  • how do we effectively identify those goals?
  • how do we attain consensus on what those goals are?
  • what do “success”, “good” and “OK” look like for everyone involved?

If we step back, agile is just a marketing term – a simple pattern for a collection of mostly proven ways in which we believe we can work effectively. Where we need that marketing or verbal anchor, let’s use it – (much like we’ll use whatever agile practices and culture we know are useful in attaining our stakeholders goals) – but let’s ensure we’re not having methodology and culture conversations for the sake of methodology and culture alone.

Before diving into “agile” discussions, step back and (re-)establish what success should look like for your customers and users from their perspective.

SMART Goals and The Elephant Test

Posted on by
Reply
Reading time ~ 2 minutes

Just under 4 years ago I set myself a goal to “socialize the concept of technical debt” within my organization. I had a strategy but no visible means of measurement. When I’d achieved my goal it was obvious that I’d succeeded but I had no direct evidence to prove it. – and why bother? – I succeeded.

Thanks to Luke Morgan (Agile Muze) for the inspiration of the “Elephant Test” – I’d never heard of it until last week.

For years everyone I know has been indoctrinated into using “SMART” goals (as defined in the early 1980s). As a line manager, employee of multiple large corporations and one-time domain expert in learning and performance management systems I too bought into and supported the “SMART” mnemonic.

Here’s a challenge – try running a 5 whys exercise on each of the attributes of SMART.

  • Specific,
  • Measurable
  • Attainable
  • Relevant
  • Timely

I can develop valuable meaningful responses (not excuses) to most of these except measurable.

I’ve spent enough years working for corporations that love to measure to have a very good handle on the values and dangers of measurement. But until my inspiration from Luke, I never had an alternative.

Today I do!

Why measure something when you implicitly know, trust and recognize what you’re looking at?

The Elephant Test “is hard to describe, but instantly recognizable when spotted”.

A big leap in agile management is trust. Trust your teams to do the right thing.

  • If you trust your team to set and accomplish their own reasonable goals, you must also trust their judgement.
  • If you trust their judgement, they must be able to recognize when they’ve achieved a goal.

Measurement is the most brute force way of recognizing something – but not the only way.

Software development and management is a knowledge activity. We tacitly know what’s right and wrong and we openly share that recognition. Occasionally we choose to measure but much of the time we trust our judgement and that of our teams.

So if the team says they saw an Elephant, chances are they saw an elephant.

Or don’t you trust them?

If that Elephant happens to be that your team believes they’ve met their goal and their stakeholders agree, why must that goal be explicitly measurable?

I know when I’ve made a difference and those around me know when I’ve done a good job. That team consensus is far more rewarding and more trustworthy than preparing measurable evidence – it’s also a lot harder to game and a lot harder to sub-optimize your behavior to group perception than around numbers.

Next time you’re looking at goal setting. Don’t go overboard on making them all measurable. If they can pass the elephant test, that should be more than sufficient.

Try starting out with a clear simple vision, good direction, a suitable time window, a strategy and some commitment to do the right thing and work from there. You’ll know amongst yourselves when elephant-testable goals have been achieved (and delivered in good faith). These may also be some of the most valuable impacts your team can have.

Building a Case for Change

Posted on by
Reply
Reading time ~ 3 minutes

I recently led a short evening session discussing strategies for collective code ownership. We opened with a set of patterns and practices but the team highlighted something painfully obvious that I’d overlooked…

What’s the business value and driver behind collective code ownership. What’s in it for your product owners and customers?

So often we focus on the people barriers and technical challenges to collective code ownership without recognizing that the barriers may be organizational or financial.

This challenge happens when you attach yourself to “the right thing to do” and seek to progress without recognizing that the population you’re likely to be working with will fall across a spectrum from complete support, through “don’t care” to disagreement and dissent.

If you want to pursue a strategy for collective code ownership, step back and work through the following questions (some of these are hard – consider starting by brainstorming with a small supportive team):

  • If we just got on did it, would we be successful?
    • Yes – Great, you’re working with a team and business that “gets” this or trusts you to do the right thing. You could stop reading here, but you might want to skim this to see what ideas & thoughts are triggered.

    • No – OK, you’re part of the more normal population (for now) read on for some ideas. You might not need to cover all of the following (and if you do, it might slow you down)

Still reading? – Good!

The following apply to pretty much any change or investment program but answering them is surprisingly hard. Your context will probably differ to mine so I’ve not given all the answers today.

  • What are the top 1-3 benefits of pursuing this?
  • What are the top 1-3 costs of pursuing this?
  • Are there people outside the team that I’m going to need to “sell” to?
  • Are there people inside the team that I’ll need to sell to?
  • What are the risks, pitfalls and political or personal agendas?
  • What do we sacrifice – what’s the opportunity cost?
  • Who are my supporters and how can they help me?
  • Who’s on the fence, do they need to be involved and how can they help/hinder?
  • Who will fight against this and how big a problem is that really?
  • Do I ask for permission and support or press ahead and ask for forgiveness later?
  • Who will this impact and in what ways (positive and negative)?  **detail below

**How about those stakeholders?

For the set of stakeholder questions I suggest you’ll achieve better flow and find natural breaks if you cover positive and negative aspects for each role by “switching hats” as you work through rather than batching up all the positives first.

  • What’s in it for you and what’s the down side?
  • What’s in it for your peers and what’s the down side?
  • What’s in it for your boss and what’s the down side?
  • What’s in it for your team and what’s the down side?
  • What’s in it for your business and what’s the down side?
  • What’s in it for your users and what’s the down side?
  • What’s in it for your customers and what’s the down side?
  • What’s in it for a product manager/owner and what’s the down side?
  • What’s in it for a project/program manager and what’s the down side?
  • What’s in it for an individual team member and what’s the down side?

Wow! that’s a lot of questions.

As I said – you might not need to answer all of these and you really don’t want to have to write them all down but it’s worth spending a few minutes or hours considering these if you’re planning to invest your time, effort and credibility in something you believe in.

Beyond everything here, I also recommend a read of Fearless Change to help you on your way.

Software Is Just A Means To An End

Posted on by
Reply
Reading time ~ < 1 minutes

Last year Chris Matts wrote an insightful post reflecting on the Agile Manifesto and business analysis. At the time it sparked some creative thinking but I didn’t turn it onto the right words.

Now I have them.

Writing software is just a means to an end. Our customers and users don’t always want software (with the exception of games). They want to be able to achieve something and fulfil their role.

Software was developed to help us achieve things in more effective, efficient, accurate ways. We have CAD tools because it’s seen as better than traditional draughtsmanship. We have Financials applications because it adds more value than traditional double-entry book-keeping. Software is written for commercial fighter aircraft because we made them too complicated for people to fly alone.

I could go on…

Remember you’re solving someone else’s problem or making someone’s life easier or safer, not just writing software for the sake of software.

The next time you think about adding a speculative “neat” feature or idea to the backlog, think about who will actually get value from it.

Admittedly, sometimes it might just be to tick the box on an RFP in which case your investment should be lower than if you’re delivering for real end user value but there is business value in doing something.

Writing Code is NOT a Value-Add Activity

Posted on by
Reply
Reading time ~ < 1 minutes

I’ve been working through David Anderson‘s last book; “Kanban“. Last Night towards the very end of the book I had a lightbulb moment.

When taking a lean approach to software development you need to focus on value-add activity. David’s acid-test for this is very smart – I paraphrase below…

“If it’s really a value-add activity, then you should be striving to do more of it”

Now, consider this. Are we writing code or delivering working valuable software that solves a customer or user business need?

Some of you may have worked in organizations that considered measuring programmer performance by lines of code produced. Like all great metrics, there are some fair reasons for measuring LOC but with the wrong motivation, it will drive the wrong behaviour. You’ll produce more lines of code but not more value.

So…

Writing code is not a value-add activity. Producing working software that our customers and users need is.

Remember the concept of 4GLs – the more coding activity you could automate, the more real output you can get.

This approach is still relevant. Great software development teams automate as much of the coding as possible so that teams with strong domain expertise can focus on only writing the advanced business logic and don’t have to worry about the scaffolding.