How To Create Project Documentation That Doesn’t Suck

Filed under Lean, Productivity, Techniques | Posted by PMStudent

A discussion on management plans started by my friend on Govloop recently about management plans got me going.

My thinking on the topic of documentation in general has matured over the last few years. I don’t think I know everything though, far from it.

What Makes Project Documentation Suck?

There are several common problems people fall prey to when it comes to project documentation.

  • All text, very little visuals
  • Documents are longer than most short books
  • In the weeds – over reaching the intended scope
  • Assumes the person reading the documentation is a chimpanzee
  • Describes a theoretical alternate universe which has no correlation to reality
  • Written for the wrong audience – trying to please management instead of making it useful for people who actually need it

Who Falls For It?

Three types of people in my experience:

  • New project managers, who think templates and paperwork is what project management is all about. Analysis Paralysis is prevalent.
  • Veteran project managers who have become detached from the technical aspects of their teams’ work, and retreat to documentation land.
  • Project managers who go with the flow and don’t question the organization’s tendency to have management plans with 1,000 pages that no one will ever read.

What About Standards?

I’m speaking mostly of management plans now.?I like standards and best practices documents. Travis listed some good ones:

  • PMI?s The Standard for Program Management
  • DI-MGMT-81334B
  • MIL-STD-881
  • INCOSE SE Handbook
  • ANSI

But starting with standards is a mistake.

The starting point should be the reality of “how things get done around here.” That’s not going to be easy – usually there are many processes which are not well defined in any organization, and half your time will be spent interviewing people who actually do this stuff on a day-to-day basis and consensus-building for those processes which are not well defined and/or have contention among staff on the best method.

Seldom is there no organizational or project history to draw on; If this isn’t your first project in a start-up company you can start by mapping reality. After you’ve made a baseline document, then you can start incorporating ideas from standards and best practices (internal and external).
When you start with standards:

  • The plan is great in theory, but not in practice (reminds me of a Yogi Berra quote)
  • The plan doesn’t resemble how things actually get done, and so lacks credibility with staff
  • The plan employs a lot of fancy language and references to standards no one understands but the author, adding to the probability it will not be read or followed

When you start with reality:

  • You facilitate the writing, but the primary source is the stakeholders of the processes ( = buy in! )
  • You gain a deep understanding of how things actually work in the current state – this deep knowledge of the domain is the only way to write a credible plan
  • You start with a credible and accurate plan, and can iterate from there – knowledge of the standards out there can now be useful…it’s only useful if you’ve gained the deep knowledge of the processes in your specific context


  • A plan without majority input from the staff who will carry it out is doomed to failure
  • Attempts to change and dictate new processes in a document are doomed to failure; that’s doing it backwards. Unfortunately that’s exactly what most organizations do, especially in government in my experience. First, gain understanding and build consensus through conversation, drafting visuals of processes, etc. Then document it as concisely and clearly as possible.

Changes follow the same process:

  1. Understanding
  2. Discussion/drafting
  3. Document

How To *Gasp* Make Documentation Valuable

With process documentation and management plans you must always ask what adds value in the majority of cases, and what doesn’t. It’s the 80/20 rule.

After deep domain knowledge of the processes in use is gained, you’ll know what the most critical processes are, and which scenarios happen most of the time.
Don’t bother trying to account for every possible scenario. It’s muda (waste) in my opinion.
Guidelines from my perspective:

  • Must be less than 10 pages in length
  • Must be primarily visual with supporting text, not the other way around
  • Highest Effective Level of Detail – in the weeds is not where you want to be, document at the highest level possible that still gives appropriate guidance and answers the right questions for actual users of the process.
  • Don’t assume the users of processes are nincompoops – I’ve seen too many plans like this – assuming people won’t know how to tie their shoes unless they reference the plan is a good way to make it unusable and even insulting – users are smart in general

What do you think? Am I dead wrong, or do you agree with some of this philosophy?