I guess it comes with the experience - after you do couple of projects you start noticing things and patterns between those. After some time they start to fit together ("click") and make much more sense than initially. But there are things I was always finding absolutely obvious - in my opinion these never required any proof. One of them is:

Stick with The Single Version of Truth within your project docs (and not only them).

What does it suppose to mean? The best illustration would be a negative example of breaking this rule. The real life example from near past on Project X …

Let’s assume you start the project with collecting some coarse-grained business requirements - you (and / or your team mates) put effort in preparing some kind of document that played some kind of role, but … now you discover that you urgently do need to start the development - so you pick few bits of functionality and describe them in a new document.

Obviously, your basis is what was in the previous document, but you create the 2nd one from scratch, aiming for different level of detail, different audience (programmers) and different scope (just the functionality you need developed now).

As you’re working on 2nd doc, you don’t have time to update 1st one (if things occur). Well, what for? 2nd one is the most important at the moment, isn’t it?

Perfect. Time for some test scripts. Obviously, the specification for development doesn’t really look like a test script - it’s a different perspective on the same functionality! So, let’s create another document. The easiest way is to do it looking at what’s actually developed already (how do the forms look alike, etc.). And if you feel there’s a need to polish something out, let’s just create a SIR and update the scripts (and forget about documents no #1 and no #2).

That’s pretty much (short version) what I’ve found in Project X.

Let me enumerate their biggest problems and mistakes that happened there:

  1. They were trying to reach several groups of people (developers, testers, business owners) and they didn’t think about ubiquitous language at all.
  2. They’ve completely ignored the required coherency between requirements, development artifacts and test scripts. It was not possible to track / validate anything.
  3. They went “short-cuts” - they didn’t have a vision of what should the documents contain (what’s the PURPOSE of the document), so they didn’t bother with keeping them up-to-date.
  4. They didn’t bother with "definition of done" on ANY level - starting with the requirements, ending with test execution. Pretty much no requirement was “finalized”, etc.

What was the result? A mess. No, it was A MESS. M_E_S_S:

  1. The test scripts were based on … hell, I don’t know what they were based on (and how to validate them).
  2. It was not possible to tell the level of completion on any level.
  3. The developers had their tasks assigned via phone or mail, without any possibility to track progress / status
  4. When there was any doubt about how something should look alive in the application, developers where clueless about where to get this info from … So they were usually asking testers - each one asked the one who he knew best (and whole matter was quite new for these poor testers).

I’ll stop here, I think you’ve got the point. And most likely you’ve already figures out what had to be done:

  • Put some effort in having just 1 ubiquitous language (and stick to it in both UI and API)
  • Figure out what to write down (the purpose of document(s)) to keep documentation maintainable and useful
  • Make sure that there’s absolutely clear what’s the status of documented information - is it approved, confirmed, to be verified, to be communicated to stakeholders, etc.
  • If you HAVE to present different views on the same entity (for instance, create test cases for collected requirements) keep the reference, so it’s possible to validate the necessary changes.
  • Don’t duplicate the same information. Never. Ever.
  • If you deprecate any information / document, either deprecate it fully or make sure it’s absolutely clear which part is deprecated.
  • Keep everything indexed / marked with constant IDs, so you can easily reference to whatever you want.
  • Structure the information (think about the form up-front), so the readers don’t have to strangle with something that looks like a digital scratchpad

Damn, this post was supposed to be brief. Sorry for that, but I was quite shocked with what happened with this project and I thought it’d be good to publish that so I can publish these observations. Hopefully you’ll find them useful.

Share this post