.sds-sidebar{color:#fff;}

Traceability is the Key to Usability for System Documentation

Aug 29, 2016 8:55:25 AM / by PaulG

But where is the system documentation?

Ever heard this question?  How do you answer?

Here are some common and some not so common answers and my thoughts:

“The best documentation is the code”  -  I used to say this, theCucumber-Selenium-Code-IDE.pngn I started working with a Hadoop team. Systems are built to be testable, deployable and maintainable at the system function level – not at the user functional level. 

So yes if you can read code, you can figure what each part of a system does – but likely you can not see how those parts work together to create value for the user. Well documented code is great for developers – likely no-one else though.

“The team updates the training manual each and every sprint” -  This is wonderful if it is part of the definition of done. But do you really want your software team updating training documents? Maybe so if the training docs are embedded in the system  help and Screenshot_2016-06-14_14.44.50.pngdelivered to the user with the software. This is great documentation for users. And items like user instructional videos and playbacks of how to perform a function in the system should be considered part of documentation. Does it help the anyone else?

So now we are getting to a deeper question.  What documentation is needed?

Answer:  just like anything else – as little as possible.  I know, I know – that sounds like a cop out. But it really isn’t. 

Some organizations need to be able demonstrate that they are working how they said they are going to work- they are following the process they declared to be their standard.  Think regulation. Think what auditors are looking for when they come knocking on the door

And every  organization needs to document what is necessary to make it easier for new team members to get up to speed or to aid in speeding up researching a bug. Because let’s face it, as much as we want long lived teams, and we want to produce pristine code, neither of those really happens. 

So here is my thought: Don’t think documentation, think about what problem are you trying to solve.

If a new team member needs to get up to speed on the system -  I point them to tests. 

Functional tests tell the story of how a user should interact with the system – if they are traced to the user stories then you solve the problem of speeding up learning for a team member. Cucumber-Test-Results.pngOh, and by the way – you also solve the problem of demonstrating to those pesky outsiders of demonstrating that you are working like you way you are going work.

 

 

Unit tests tell the story of how the system is constructed –  new engineers can easily follow them to figure out what each system component does and doesn’t do.  CodeCoverage.pngNow, if the unit test is traced back to the version of code that a particular story was completed – then you have traceability. 

If a user reports a bug. Well that bug is in a feature, and that feature has a set of stories associated with it, and those stories have test cases tied to them. And those test cases were written for a particular build of the software – hmm if this is all transparent (meaning traceable) – it  pretty easy to quickly target what you need to update to make that user happy.

 

So back to our original question.  But where is the documentation?

Answer – It can be delivered with the system. It is in the user features and stories, it is in the functional test cases, it is in the unit test cases, it is in the code. It is everywhere.

What makes it useful? Having the ability to tie all these together through traceability.

Traceability.bmpTraceability is not easily achieved. If you want it to be easy you have to dedicate time and effort to setting it up. Integration between your Agile Lifecycle Management tool (ALM), source code control system, bug management system, test management system and release management system maybe required.

 

For one of these set ups on testing, check out Jack Ozment's post on using Jira and Zypher.

 

 

 

Written by PaulG

Subscribe to Email Updates

Lists by Topic

see all