Writing by Peter Hilton

Book review: Epic Alignment

How to write structured feature documents 2020-10-13 #product #book #review

Epic Alignment

Epic Alignment, shows product managers how to write feature documents, or ‘epics’. Nils Janse’s detailed treatment of a specific topic delivers a medium-length e-book, and a smooth and accessible read.

RX - reader experience

I most love this book’s clarity and structure (with its illustrations a close third). The writing avoids the fluff that makes some books twice this length, without the kind of density that forces you to read each sentence two or three times. This clarity also extends from the writing to the book’s structure.

The book starts by summarising ‘the book in four pages’, introducing four top-level recommendations that return as chapter titles:

  1. Drive towards impact, base it on research
  2. Embrace user stories as a shared language
  3. Use a single source-of-truth to create shared understanding
  4. Expose micro-decisions through explicit questions

Each chapter repeats this structure-as-content on a smaller scale, by breaking each recommendation into more specific recommendations in their section headers. Product managers’ anecdotes give another example of this usability - reader experience (RX) if you like - that makes it easier to return to the text later. These stories appear in separate sidebars, not buried in the main text.

Structured writing

The book’s consistent hierarchical structure should not come as a surprise. Its message parallels this medium, namely that product managers can use structured writing to create clarity in the face of complexity. I see what you did there, Nils!

The book follows its four-page summary with a chapter establishing the author’s approach to project management. Perhaps not everyone needs that, but I appreciated the alignment and how naturally it introduces the next chapter: the first recommendation, about impact.

The next chapter then introduces structured writing in the form of user stories and user story mapping. That chapter, in turn, prepares the reader for the book’s key vision for a single source of truth for understanding new product features: the feature document. The penultimate chapter refines that, with a recommendation for recording decisions, and the last chapter shows an example feature document.

Agile documentation

While this book might only work for people who like both structure and writing things down, it might also demystify both for people who don’t. Either way, I recommend it even if only for an example of what agile documentation can mean.

Agile software development’s focus on working software over comprehensive documentation did not make documentation unnecessary, despite much wishful thinking, but rather highlighted the difficulty of identifying useful and necessary documentation. This book explains one kind of documentation that can achieve both standards, in some contexts. For that, I value this book’s modern take on a technique whose roots lie in pre-agile documentation - functional requirements specifications and product requirements documents.

I would only wish for this book to improve one thing, or perhaps showcase in a follow-up: side-by-side annotated example feature documents. The last chapter introduces an example document only grudgingly, and the explanation appears separately from the example. Apart from that, I hope that enough people read the book to persuade the author to release a print edition for me to keep at hand on my bookshelf.

Peter Hilton reviewed the final version of this book after having previously reviewed and provided feedback on an earlier draft.

Share on TwitterShare on LinkedIn