The Joy of Peer Reviews (Part 2 – Documentation)

Share
Reading time ~5 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.

One thought on “The Joy of Peer Reviews (Part 2 – Documentation)

Share your thoughts...