How To Create Project Documentation That Doesn’t Suck

A discussion on management plans started by my friend here on Govloop 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? click to tweet this quote

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?

Leave a Comment


Leave a Reply

Dennis McDonald

Great post, especially the sentence “The starting point should be the reality of ‘how things get done around here’.” I’ve never managed a project where any external methodology could be adopted without modification so paying attention to how things are run really makes sense. For example, if the client doesn’t care about tracking costs, don’t try to track costs. That sounds absurd, but it happens.

That said, I think the concept of documentation needs to change. FOrget committing things to paper. EVrything needs to be online, accessible, share-able, commentable, and updateable.I’ve never seen a plan that didn’t have to be modified before the end, so keeping that in mind right from the start is important. Assume things will change and be prepared with a process to support the change.

Dennis D. McDonald, Ph.D.

Alexandria, Virginia

Stephanie Sieradzki

I am left speechless at how stunningly accurate this is, but more importantly how depressing it is that SO many PMs that I have worked with fall into one of your “3” cited above. Fear of thinking?

Josh Nankivel

@Dennis, a great point. A wiki as documentation, or even better, something like the functionality Google Docs provides would be awesome. I’ve used the commenting feature and versioning multiple times with groups of people and it’s awesome. Rather than having a big production at every configured version of a document, there’s no reason why the configured versions shouldn’t be painless and quick to update.

Josh Nankivel

@Stephanie, so true. I don’t think it’s fear of thinking though, more just getting sucked into the status quo.

Dennis McDonald

Josh I would be careful about using a wiki or even Google Docs if the group includes folks without experience with those platforms. A recent attempt to use Google Docs in a collaborative situation foundered because of the difference between the Docs file organization and naming conventions and the more traditional structures the staff were familiar with. It will be interesting to see how Microsoft handles the integration of SharePoint with Yammer. Knowing Microsoft, though, they may tend to oversell the “out of the box” capabilities of the platform. But I agree the trick is to retain a core of documentation that provides a reference point while allowing collaboration and discussion to take place around that so as to reflect the dynamic nature of the project. (I address some of these topics in “Balancing Structure and Flexibility in Collaborative Project Management” ( and would be very interested in your take on this.)

Josh Nankivel

Very nice Dennis, and a good point. I’ve only used Google Docs you do have the ability to enable commenting and restrict editing. This may be a fairly recent feature, I’ve only used it in the past 6 months or so.

Staff will definitely need to be transitioned and trained on a change like this…perhaps with a few smaller pilot groups and documents first and then the pilot group can help train the rest of the organization as it rolls out.

What document/wiki functionality does Sharepoint have (I haven’t used it personally for years) and is it any good?

Josh Nankivel

@Steve – maybe it’s just me, but I love documentation that is primarily visual in nature. But most is the reverse…lots of text and the authors decide to throw some visuals in later on to compliment the text.

Josh Nankivel

Unfortunately no, but I absolutely would love it. High-level conops and use case diagrams would do wonders for making project objectives clear, and a visual representation of the time-phased budget.

Stephanie Sieradzki

I’m in the middle of being a member of one (a small internal business process improvement project) that has probably spent more time on ensuring the “right” paperwork is in order than the time it will take to make the entire change the project is focused on bringing about. I think that’s a failure. If the cost of planning is more than the savings you will get out of the project, that’s a serious failure, even if the improvement is implemented successfully.

Josh Nankivel

When it’s death by a thousand cuts Chris, it’s hard to point to one thing and say “that’s what did us in!” – I think that’s the wrong question. The question is for this particular aspect (documentation in this case) what is the likely difference in ROI between the two scenarios?

Dennis McDonald

Going back to Josh’s original post, a problem arises when “paperwork” becomes divorced from the underlying process it is supposed to address. No one would suggest., I think, that it is unnecessary to develop a succinct description of a project’s goals and how it proposes to achieve those goals.

For example, it’s normal to include such a description in a document called a Project Charter. If the processes for developing and communicating the Project Charter are inefficient, that’s one thing. We’ve all seen instances where paperwork related tasks seemed to overwhelm the underlying purpose of a document’s content. Evidence of that is seen in practically every office where unused three ring binders sit on shelves gathering dust.

It’s quite another thing to suggest that developing and agreeing on a Project’s Charter is unnecessary. Failure to agree on what a project is trying to accomplish ALWAYS will bite you.

The trick is to balance (a) the need for capturing key content elements in a form that is accessible against (b) the cost of doing so.

My view is that the larger and more complex the project, the more need there is to collaborate and share in the process of developing and sharing basic process documentation. If the processes being documented are unnecessary, do away with them. But if they are necessary, document and communicate them efficiently.

Mihail Sadeanu


It is interesting that nobody tried to comment what happens when you start using a real project management methodology, not a standard.

In my former discussions I have mentioned the PRINCE2 PMM intensively used in many programs and projects (not mentioned in the posted list of standards). Although it provides official coupled templates and the mandatory project management documents are complex, requiring to be assembled with all mentioned paragraphs, I never went to a deadlock using it even in very complex internationally deployed projects for which the client part did not provide a certified practitioner project manager in this direction.

It is the professional art of experience from the part of the provider program/project manager to conceive and offer a correct and compact project management documentation under the heading of the general “Program/Project Management Plan” (including the schedule plan, and a Project Charter or a Project Initiation Document) to really make it attractive for all the program/project stakeholders and for the real utilization of all its statements/content along the program/project deployment. However, it requests some years of experience with comfortable clients.



Josh Nankivel

Thanks for your input Mihail. I haven’t personally looked into PRINCE2 in detail and what the documentation looks like with PRINCE2.

Jo Youngblood

PRINCE2 is more popular in England than in the US, but is still a very adoptable PM standard. It’s comparable to PMI as a PM framework. Good stuffs!

Loved the post Josh. Especially about writing at the highest level of detail and not assuming your audience lacks the ability to think.