Category Archives: Project Management

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.

Escaping the Oubliette (Part 4) – The Litter Patrol

Posted on by
Reply
Reading time ~ 2 minutes

As promised in my last installment on oubliettes…

Your team might not be fully ready for the merciless refactoring encouraged by some agile approaches but this will help you stay heading in the right direction whilst keeping the delivery vs refactoring impacts balanced out.

The cost of change has a (roughly) logarithmic relationship to debt. I’ve seen first-hand how high-debt systems become almost impossible to change and it’s not pretty.

In a debt-ridden system we are eventually faced with a choice; refactor or replace. Eventually even once-newly-replaced systems build up debt and the refactor/replace choice returns. Craig Larman & Bas Vodde’s most recent book covers the debt/cost relationship brilliantly in the section on “legacy code”. They also describe the oubliette strategy of “Do No Harm” or as I call it – “The Litter Patrol“.

This is a particularly powerful debt management approach as it’s both a prevention and reduction strategy.

Here’s the basic concept…

When working with an area of legacy code, you’re working in a particular “neighbourhood“. If that neighbourhood is untidy your care and attention to that neighbourhood is diminished. Much like the “broken windows” principle; once the damage seal is broken, neglect and further damage follow and overall code quality deteriorates rapidly.

So (without going overboard), every time you’re working in a particular neighbourhood, what can you do to clean up a few pieces of litter?

Not the run-down shopping district between lines 904 and 2897 but more the abandoned classic car between lines 857 and 892 or the overflowing trashcan on the corner between 780 and 804.

If you introduce a litter patrol in your teams and encourage a hygiene cycle with every change to your code, your debt load and future cost of change will rapidly reduce for the areas you hit most frequently.

Unfortunately although this is easier than a complete refactoring of a poorly designed class-hierarchy or monolithic god-class, in order to perform the litter patrol in safety on your code you need good unit tests or small functional tests for that neighbourhood and ideally some refactoring support (I like to call these your gloves, garbage bag and litter picker).

This challenge doesn’t mean don’t do it. In fact if you don’t have tests already, maybe your next patrol isn’t changing the code at all but to write just a couple of small, independent tests to demonstrate how that area is expected to behave. (You might even need to make some tweaks to make it testable)

If it’s hard, don’t avoid the problem, focus on making life easier one bite or constraint at a time.

Every time we successfully deliver a small clean-up task, the future cost of change to that area is reduced and our incentive to keep it clean is improved.

Look out for part 5 – sponsorship – coming soon.

Escaping the Oubliette (Part 3) – Bug Blitz

Posted on by
Reply
Reading time ~ 3 minutes

Every product team I’ve ever worked in had a bug blitz at some point and often one every year or two.

There’s no arguing that a decent bug blitz is a powerful way of getting the numbers down and clearing all the bugs in a good, solid drive feels good but the necessity for them is caused by a buildup from somewhere.

If you find you’re needing a bug blitz on every release, take a look at your defect and debt prevention activities and make sure you’ve got some topping & tailing practices going on.

Usually bug blitzes are performed at the end of a project but if you’ve not done so before, try having a 4-8 week blitz at the beginning instead. You’ll run quicker afterward and (if you keep things under control), you won’t have to worry about having time to mop up at the end.

Once you’ve got the numbers down, set your maximum defect threshold (or ratchet) at this level for the remainder of the project and keep this new lower level sustained throughout development.

What’s good about a bug blitz?

A blitz is particularly useful if you can focus on areas of the product you’ll be working with soon. It’ll get your team working together (particularly if they’re newly formed) and familiar with these areas before all the major work starts.

Couple this up with developing some decent automated tests in those areas as part of the defect fixing and you’ll be developing a much safer scaffold for your new work and reduce regression risks during your next release.

You could take things further and perform some refactoring but I suggest keeping different types of activities separate at this point and just stick to straight bugs. If you have a specific functional area needing a real overhaul, it doesn’t fit the bug blitz mold. I’ll cover this aspect  in more depth when I talk about “sponsorship” for debt reduction.

I use bug blitz approaches when training up new staff. I review the defect backlog for a particularly grubby functional area and have a pair of staff take custody of it as caretakers. We pipeline the defects so that they can start with some simple introductory ones (usually low severity, noise or cosmetic stuff) and once we get confident in these we expand out into adjacent areas – it usually takes a month or two for them to really get warmed up.

The bug blitz is also a great opportunity to start new release development with a clean slate. It means no mixing types of work during feature development and gives you an opportunity to scrub the grime out and get a few new scaffolding tests in place.

What about the down-side?

First; they cost time and money. If you dedicate a team (or most of a team) to a blitz you’re not delivering anything new. This is obvious but important. What’s the impact of a month’s delay to your next release? (assuming you can ship with those bugs in there). And what will that delay do to your stakeholder relationships?

Be mindful of the impact a bug blitz can have on your customers. A high level of churn on existing functionality can be really dangerous. You might need to make a point of jumping through a few hoops to retain backwards compatibility.

Don’t be too hasty to refactor if customers are expecting certain things. If you don’t have decent automated regression tests, you really need to ensure you write at least a couple that hit the same area before you fix any defects. (I usually expect my developers to deliver at least 2 or 3 new automated tests with each bug fix).

Worse still, I’ve seen a batch of fixes in a functional area radically change behavior “for the better” according to the developers that raised the original internal defects who then discovered that customers were actually depending on existing behavior or had developed their business processes around the issues.

Sometimes, even if you think it’s ugly, it might be that way for a good reason.

With enterprise software, you’re often looking at heavily customized implementations, some of which have taken years and millions of dollars to evolve.  Smacking these with a mountain of churn on existing functionality can be painful and expensive for your customers. Whilst it makes your numbers look good, consider whether some things should really be touched.

In summary. Bug blitzes are a great way of starting with a cleaner work area and ramping up teams but beware of backwards compatibility, customer impact, time and cost pitfalls.

Read part 4 – “the litter patrol“

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.

Escaping the Oubliette (Part 1a) – Debt Prevention

Posted on by
Reply
Reading time ~ 2 minutes

This is a partial re-post of Escaping the Oubliette (Part 1). I’ve split the article into smaller readable components.

Great, I’ve got my incoming defect strategy nailed,

Now how do I prevent defects and debt in new code?

In 5 words…

Continuous attention to technical excellence.

Here’s my top 7 (there are plenty more)

  1. Acceptance Criteria – Be really disciplined on your acceptance criteria & acceptance tests, team up with Analysts, Testers, Product Owners if you have them and attack your stories from every angle. A good approach to this is a “story kick-off” where the whole team dismantles a story before starting.
  2. Thinking Time – don’t just start coding right away, task things out, try the 10 minute test plan, discuss your approach with your peers and for more complex or large items, try the “just enough design” approach.
  3. TDD – It’s hard to start but has an immense impact.  I’ve just seen a team complete their first project using TDD. 3 weeks into their final round of post feature-complete testing, their defect run-rate hasn’t had the testing spike seen on prior projects. In fact they’re keeping on top of all new incoming defects and have time to start paying down the historic backlog.
  4. Pair Programming – Do it in half-day trial chunks if you don’t have the stomach for going full-tilt. I’ve performed remote pair-programming with colleagues across the Atlantic using decent phone headsets and online collaboration tools for hours at a time. The net result of 2 days of remote pairing was finding and fixing about 10 extra defects in a thousand lines of code that neither of us would have found coding alone.
  5. Peer reviews – there is still a huge space for these in agile teams. But here’s the thing. Be really tough. A peer review is not a hurdle. It’s a shared learning exercise. Functional correctness is actually the smallest component of a peer review. You should trust your developers that far. But there’s a whole series of other aspects to review. See the joy of peer reviews.
  6. Small tasks – I once worked with an outsourced team who when taking work would disappear into a hole for 2 weeks and return with a single task in our configuration management system containing edits to 200+ files and multiple condensed edits to the files. My rule of thumb is one reviewable task per activity. If you’re going to add new functionality and refactor, that’s 2 independent tasks that can be identified and reviewed separately. This means you should be able to easily deliver 2 reviewable, closable tasks per day.
  7. Fast Builds – make it insanely simple for a developer to perform an incremental build that validates new code against the latest main code line. (small tasks are a big help here).  This includes the right subset of unit and functional tests. Aim for a target of a 30 second response time or less between hitting the button and seeing the first results.

In the next article in this series I’ll focus on “Tailing” – How do you start reducing the old defects.

Readiness to Serve

Posted on by
Reply
Reading time ~ < 1 minutes

A couple of years ago a friend said: (I’m paraphrasing here)

My team are paid a huge pile of money to do nothing most of the time.

As an analysis team for a financial institution their goal was to be immediately available at the first sign of an anomaly in the system. Like every other good analysis team in the city, their goal was to identify and find a means of exploiting the next new anomaly before anyone else in the world did. When the rest of the world catches up, their edge is lost – until the next time.

Many times I see organizations saving pennies on billions of dollars of revenue to ensure they keep their teams “busy” or “fully utilized”.

  • If your teams are always busy, how will they be able to cope with the next bump in the road?
  • If your teams are always busy, how will they be able to stop and see the big picture?
  • If your teams are always busy, when will they have enough time to stop and sharpen their tools?
  • If your teams are always busy, who is looking around to see what the rest of the world is doing?
  • If your teams are always busy, who will you have available to exploit the next change in the market before your competition?

Unless money really is that tight, staff up your teams or balance your investment portfolio not just to deliver your current needs but also provide sufficient capacity to be “ready to serve” when the next anomaly hits your market.

Blame

Posted on by
Reply
Reading time ~ < 1 minutes

When your project goes wrong because you’re dependent on another team, whose “fault” is it really?

  • When did you identify the risk?
  • What did you do to mitigate it?
  • What relationship did you build with the team you’re dependent on?

When did you start really collaborating to resolve the dependency?

Too often we throw our problems over the wall and blame the people that aren’t there to catch it for our own laziness.

  • Are we too lazy?
  • Are we too busy? (what else is more important?)
  • Are we secretly looking for someone to take ownership of our problem?
  • Are we cynically looking for a scapegoat?
  • Are we just incompetent?

Think about government lobbyists – they spend their entire time fighting for what they need to achieve…

If something is that important to the success of your goals, why aren’t you sat next to the people you need it from making sure it’s on the top of their priority list too?

YOU ARE RESPONSIBLE FOR YOUR OWN COLLABORATION FAILURES

Captain, You’re Wrong!

Posted on by
Reply
Reading time ~ < 1 minutes

With limited time and bandwidth, leading a large global development team on a large complex project requires rapid decision-making on difficult problems.

Some years ago my team found the cost of delay on a wrong decision corrected later was generally far lower than the delay of holding out to be sure of the right one.

Many times I had to look at what little information we had and either make (or support the team in making) an arbitrary judgement call.

The reason this approach worked for us was that we were all willing to step up as soon as we knew were wrong (usually in light of new, previously unknown information) and call each other out. In fact I took it as a matter of personal pride that I could be wrong so often and yet my team could still outperform those around us.  In that team it was socially acceptable to be fallible and we encouraged less-experienced staff to challenge their more experienced counterparts.

The phrase “Captain, you’re wrong” is still music to my ears. It usually meant someone on the team was right!

Try this: When you’re stuck making a decision, choose the one that seems least wrong. You’re an experienced professional, sometimes your instinct will be all you have left to work with. Make it clear to your teams that if they find a decision isn’t working for them they can revisit it – as long as we get on with it now with no debating.