In the current environment, there appears to be a subjective difference of opinions of the types of documentation and the level of detail required.

For example, at what point is a document a design document, an as-built, technical specification and operational guide?

Since the project hands over to the operational team, there is conflict in what they think they expect to see and what is delivered.

Although attempts have been made to clarify what these documents should look like, there is very little by the way of experience.

Generally these issues arise when there is an incident and documents are seen as lacking in detail.

1 Answer 1


The main concern shouldn't be 'how do we name this', but 'what information do we need to get our product or organisation to where we want it to be'. Your question to me seems to revolve around this sentence:

"there is conflict in what they think they expect to see and what is delivered."

This can indeed be a big problem, especially when work is done across multiple (sub)projects, teams and disciplines. The obvious answer is: define beforehand what the document goal is, what information it needs to supply. What do stakeholders need from this document, what actions and decisions should the document enable the stakeholder to make?

Your project workflow should include a system for ensuring the products (which includes documentation) being delivering fit purpose and add maximum value to your overall product or company goal. Scrum for instance applies a user story, acceptance criteria and a definition of done to product increments delivered. This also applies to documentation. User stories and acceptance criteria can be described in a lot of ways, for example:

  • Team x (stakeholder) who are building product x, need to be able to determine from the document, what government ruling applies to the product.
  • Team y (stakeholder) who are building product z, need to be able to determine from the document, what type of battery is optimal for supplying product z with the power it needs.

It's impossible to give a name to something that will ensure the document fit's the stakeholders purposes. Invest in making sure the document suits everyone's needs. Once that's taken care of, pick a name that fits the information contained in the document.

  • Thanks Rieks. There are conflicts pertaining to a number of things, one being the types of documents. It is however difficult to bridge the gap since very people want to define the information needed. This is due to reasons such as lack of experience, historical conflicts between teams i.e. Project and Operational, lack of ownership, etc. It seems it is easier to avoid coming to the table since if there is an issue, there is a way to simply state that 'It wasn't enough, I expected x', etc
    – Motivated
    Commented Aug 26, 2015 at 18:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.