2

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).

6
  • What is the purpose of this document? Does it describe what to build or what has been built? Who is the audience of this document? Does it add value to those stakeholders? – Thomas Owens Jan 13 at 0:15
  • I am asking 'in general' (not specifically about user guide, functional design/detailed design specs, interface agreement or else). I am curious, is there anybody, who do notice and struggle with similar issues in specs of enterprise project system/ components. – elisarea Jan 13 at 12:20
  • Isn't this a standard problem in change management? Make the document a configuration item and consult stakeholders before authorizing changes? I get the feeling that there are two related problems here and I'm only seeing one of them. The second cluster of problems seems to be about how to write design specs clearly so that they are accessible, accurate and useful to all stakeholders. CM would help with that, (The effort of managing a CI will force discussions that will provide opportunities for clarity), but I'm not sure I fully understand. VtC for clarification, then reopen. – Mark C. Wallace Jan 13 at 13:20
  • 1
    @MarkC.Wallace This question is tagged scrum. A heavy CM process would inhibit agility. Perhaps the lean principle of reducing waste (or the corresponding Agile Software Development principle of "maximizing the amount of work not done") along with some of the Agile Modeling practices of active stakeholder participation, just barely good enough documents, documenting late, and documenting continuously would be more effective than a heavy CM process. But I agree that there needs to be some more focus in the question to write a decent answer here. – Thomas Owens Jan 13 at 13:26
  • 1
    @Mark C. Wallace, yes, this is a generic problem of change management, which needs to be solved. Is there a practice of Document Specs refactoring, like what developers do? Because adjusting the design, adding more and more, it obfuscates the docs. Keeping in mind, that in order to quickly check the history of changes - there could be a history of changes, where each change formulated in a few words, and there is no need to go through the whole document. Hence the design can be refactored to keep it clearer and get rid of excess. For projects which pretend to be Agile, it should make sense. – elisarea Jan 15 at 7:34
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.

3
  • 1
    >>that they be proofread - at some point before being disseminated - with a legal eye Critical vision sounds logic. But lawyers aren't into design specification details, I'm not sure yet that it will be effective. Nevertheless, what do you think regarding a so-called 'Design's advocate' (like 'Developers advocate')? What can it be and may an experienced specific person help improve the obfuscated design specs or defend it (because it makes sense to duplicate the data, descriptions, etc.)? In my experience, the analysts don't like to refactor the design, reducing and discarding the excess. – elisarea Jan 14 at 8:18
  • @elisarea - I never thought about a 'Design's advocate' - that would be an interesting concept, that would solve the problem, assuming the 'Design's advocate' has all the relevant skills form Sales (conception) to implementation. – Danny Schoemann Jan 14 at 9:13
  • @elisarea - Correct. Legal eye was italicized, to stress that this is NOT a lawyer's job - designs and lawyers aren't a good match. :-) – Danny Schoemann Jan 14 at 9:14

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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