Differences in perspectives for various types of documentation

Question

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.

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.