Archive for the ‘IEEE’ Category

Documentation on Agile Developement Teams

Agile Teams are all about flexibility, right? Rules evolve with the project, people’s suggestions can taken on, deadlines can be adjusted internally – and within that one week sprint, the team is pretty much free to set their own pace and schedule. Its great. It allows for creativity, changes in plans and new ideas. But sometimes, it seems like documents lose some importance.

I know, I know. People get tired of hearing QA whine about documentation. But there is a reason.  In a world where you are free to find your own way, it is good to have some idea where you are finding your way too – so that you- and your teammates – all end up at the same destination. Documents provide that overview, that roadmap. They also help others to follow you- either when making revisions in the future, or when testing the final output. No matter which development style your team follows, the importance of good documentation should not be lost.

In waterfall development, documents are turn by turn directions -carefully planned and harder to change. Agile developement needs the same directions, but the exact path can be filled in as you go. By the end of the project (by the time QA starts testing), Agile teams should sh0uld have produced the same kind of documentation that waterfall teams have.

But what about QA teams? How do you go about designing your test plan when you don’t know exactly how things are going to work yet? The documents won’t be ready in advance, which means you have to keep your plan flexible… agile. You should have a good idea of the final product, so you can plan your approach, your general tests, your schedule etc very early on. As documents are updated, update the test plan. This was a big adjustment for me, as I was used to knowing in advance what all will be done. But really, the philosophy is the same- you just work in phases right behind the developers. They finish a piece of functionality, you finish your test plan and test that piece while they start filling in the documents on the next piece. QA defiantly has an important place here – and keeping an eye on the requirements, performing ambiguity review at each stage and applying those to an agile test plan are all part of it.

Because with out requirements, development really is like that old elephant story. (An awesome version of which is reposted below from this website)

It was six men of Indostan
To learning much inclined,
Who went to see the Elephant
(Though all of them were blind),
That each by observation
Might satisfy his mind.

The First approach’d the Elephant,
And happening to fall
Against his broad and sturdy side,
At once began to bawl:
“God bless me! but the Elephant
Is very like a wall!”

The Second, feeling of the tusk,
Cried, -“Ho! what have we here
So very round and smooth and sharp?
To me ’tis mighty clear
This wonder of an Elephant
Is very like a spear!”

The Third approached the animal,
And happening to take
The squirming trunk within his hands,
Thus boldly up and spake:
“I see,” quoth he, “the Elephant
Is very like a snake!”

The Fourth reached out his eager hand,
And felt about the knee.
“What most this wondrous beast is like
Is mighty plain,” quoth he,
“‘Tis clear enough the Elephant
Is very like a tree!”

The Fifth, who chanced to touch the ear,
Said: “E’en the blindest man
Can tell what this resembles most;
Deny the fact who can,
This marvel of an Elephant
Is very like a fan!”

The Sixth no sooner had begun
About the beast to grope,
Then, seizing on the swinging tail
That fell within his scope,
“I see,” quoth he, “the Elephant
Is very like a rope!”

And so these men of Indostan
Disputed loud and long,
Each in his own opinion
Exceeding stiff and strong,
Though each was partly in the right,
And all were in the wrong!


So oft in theologic wars,
The disputants, I ween,
Rail on in utter ignorance
Of what each other mean,
And prate about an Elephant
Not one of them has seen!

Document Standards

Recently, I have read some conflicting reviews on using IEEE standards for documentation and test plans. I’ve heard people say it is a crutch, and claim that if you need the document to do your job, then using it is actually harming you. This makes sense in a lot of ways.

If you approach the template like you would approach a worksheet in school: fill the blanks in with word for word answers from the book and don’t give it much thought, of course it is a crutch. It gives you a false sense that you know things and are learning, when really, you are just being prompted.  I’d hardly call that the template’s fault though. Likely, a tester who put so little thought into their test plans would have trouble adapting with or without a template. Does this mean they are not viable tools for test documentation or requirements specification?

The way I see it, IEEE templates are just that: templates. Of course no one template is going to work for every company or even every project.  The template must simply guide a person to create a living, meaningful document for your project. If used in that way, it is not a crutch but a standard to hold yourself to. You just need to remember to apply some rational thought to it instead of using it blindly.

I have found IEEE 829 (test plan) and 830 (requirements document) to be very useful on my project. They have been a good starting point for building documentation and test plans as well as providing a cohesive feel and expected deliverables for the team. I find them very flexible and easy to adapt to every project we’ve tried so far.

Some great detail on IEEE 829 can be found here – I’ve included the basic outline below.

1. Test Plan Identifier
2. References
3. Introduction
4. Test Items
5. Software Risk Issues
6. Features to be Tested
7. Features not to be Tested
8. Approach
9. Item Pass/Fail Criteria
10. Suspension Criteria and Resumption Requirements
11. Test Deliverables
12. Remaining Test Tasks
13. Environmental Needs
14. Staffing and Training Needs
15. Responsibilities
16. Schedule
17. Planning Risks and Contingencies
18. Approvals
19. Glossary

A nice overview of IEEE 830 for Requirements documents can be found here, the format is below:

1. Introduction
1.1 Purpose
1.2 Document conventions
1.3 Intended audience
1.4 Additional information
1.5 Contact information/SRS team members
1.6 References

2. Overall Description
2.1 Product perspective
2.2 Product functions
2.3 User classes and characteristics
2.4 Operating environment
2.5 User environment
2.6 Design/implementation constraints
2.7 Assumptions and dependencies

3. External Interface Requirements
3.1 User interfaces
3.2 Hardware interfaces
3.3 Software interfaces
3.4 Communication protocols and interfaces

4. System Features
4.1 System feature A
4.1.1 Description and priority
4.1.2 Action/result
4.1.3 Functional requirements
4.2 System feature B

5. Other Nonfunctional Requirements
5.1 Performance requirements
5.2 Safety requirements
5.3 Security requirements
5.4 Software quality attributes
5.5 Project documentation
5.6 User documentation

6. Other Requirements
Appendix A: Terminology/Glossary/Definitions list
Appendix B: To be determined