Design Specification Ownership: how to protect it from obfuscation and excessive adjustments on Enterprise project?

Question

By Design Specification Ownership I mean that nobody can read it right as expected except the author/ideologist/creator.

If a person works on the same project for a long time and keeps the same documents, he knows by heart all its details, shortcomings and understatements, and therefore does not indicate all the agreements that were accepted within the team or discussed with the customer.

And the further the documentation is from the code and system interconnections, the higher the degree of freedom of the design - the more confusing and less consistent the design becomes. Design docs' readability is significantly decreased because of the following:

• business than technical details (due to this, synonyms can be used instead of unambiguous terms, because 'tautology is bad', or documentation should be 'closer to the User', i.e. it should speak their's language without technical terms);
• rotation of employees within the company (between projects of different specifics, delivery projects and internal development products;
• newcomers onboarding: a new person simply 'does not feel' what it is written about. And so on.

It's a bottleneck which decreases document specs' readability, hence it slows down the validation process, and it even bothers the support team.

My question is, how do you deal with the documentation, obfuscated by the aforementioned issues or anything else? Especially interesting is the opinion of people from B2B and business transformation projects, who have experience of work with different documentation at the same time (user guides with the highly detailed user interface detalization and technical documentation, like interface agreement and deeper).

Answer 1

Take your lead from lawyers. Well written legal documents are unambiguous, and - unless you're trying hard to find a loophole - everybody reads them and understands them the same way.

How do they do that?

1. They define their terms.

2. They clearly define what they mean and what the intent is.

3. The define the scope, audience, intent.

And they even define where to go if you aren't sure - i.e. the jurisdiction where cases will be judged.

I am not suggesting that design documents should be written in the language of legal documents.

What I am suggesting is that they be proofread - at some point before being disseminated - with a legal eye.

• How much of the document is vague or ambiguous?
• How well are the terms defined?
• Is the scope clearly defined?

Clearly, you have to leave some wiggle room. You are not going to define every last pixel on every screen and every column in every database. These things can vary by implementation platform, for example.

If you don't want your intent to be obfuscated as it goes down the implementation chain, then make sure it's not open to easy obfuscation, due to careless authoring.