Featured White Paper(s)
Encryption & Key Management for Microsoft SQL Server 2008
Written by Townsend Security
Simplify encryption and key management on … (read more)
Featured Script
convert_ident_to_guid.sql
Script to find all ident columns in db, find out if they are in an index, (if so)drop the index, recreate the ident as guid, … (read more)
Modern Documentation
We had a number of people respond to the question of how/when/what documentation should be maintained during an iterative software development lifecycle. One response talks about a continuous build technique with automated system testing. Another talks about automated documentation by placing decorators or comments in your code which utilities can turn into documentation.
What I find helpful are diagrams that are more pictorial; that are not easily demonstrated in code or code documentation. This would include diagrams such as Package Diagrams, State Diagrams, Database Entity/Relationship Diagrams, Class Diagrams. These kinds of documents have great value when looking at your system from the big picture perspective. They help you better understand how a small piece of the puzzle fits into the overall architecture.
I think the response that more closely addresses my desire to retain appropriate documentation clarifies the central goals of Agile techniques and the emphasis on design.
Here’s what people are saying…
Travis:
In general terms, you are accurate in the article.
However, it appears that you have tended toward the TDD/XP flavors of Agile.
Agile does not, in its principles, place value, it assigns that responsibility to the engineers. Letting the person performing the work decide the right amount of overhead is the thought, along with the principle of stakeholder engagement.
Removing those things from the equation, leads to the type of confusion that we (Agile Coaches/Mentors) often see in the field, but generally by executives making decisions.
There are many ways to skin a cat, and agile certainly has many, but skipping modeling in favor of … is not the principle, maximize efficiency within the team would be.
IMHO.
Abraham:
I am not sure if this would help. But from my experience while working in java, as you said the design keeps changing. But from my experience, if we make use of tools like eclipse and if we make sure of commenting the code. Eclipse will generate the required java docs.
We can reduce a lot of time in document creation, but data flow diagrams and stuff is something that we have to take care of.
Elom:
What are the tools you use in this kind of environment?
Because I am using Visual Studio 2010 Ultimate, I try to use the tools implement in this IDE though it is not easy because I don’t have Team Foundation Server to integrate it with Visual Studio. I also use spreadsheet to create product backlog, release backlog and other scrum artifacts.
Do you attempt to keep your diagrams in synch with physical database releases as you go, and if so, how?
Yes I alway try at my best to synch my diagrams with my phsical database , and I do it manually, no reverse engineering stuff.
John:
So what you do is:
Phase 1
- Write a routine that replicates a code file making random modifications as it replicates.
Phase 2
- Create some test data and expected results for the desired system, e.g. a Sales Ledger
- Write some simple code that takes some inputs does some random manipulations and outputs the results. Call this the system.Run test data against the system
- If the code crashes go back to 2 and fix it
- If the outputs match the expected results then you have the final desired system already otherwise proceed to Phase 3
Phase 3
- Run the code replicator to create a new system
- Run the test data against the new system
- If the code crashes then goto step 1
- If the outputs do not match the expected results then restart Phase 3 with the original system and also with the new system
Gradually you will get multiple threads of Phase 3 running with new working systems being produced.
If Darwin was right you will eventually get a system that uses all of the inputs from the test data and outputs all of the expected results.
There you have your system.
If your test data is comprehensive enough then you also have your documentation. It’s probably easier to add a few words of explanation to the test data rather than to get a batch of monkeys to create it for you.
Do you have something to share helping developers to better maintain necessary documentation, perhaps even after the fact? Send your ideas to btaylor@sswug.org to get into the discussion.
Cheers,
Ben
$$SWYNK$$
Featured White Paper(s)
Encryption & Key Management for Microsoft SQL Server 2008
Written by Townsend Security
Simplify encryption and key management on … (read more)
Featured Script
convert_ident_to_guid.sql
Script to find all ident columns in db, find out if they are in an index, (if so)drop the index, recreate the ident as guid, … (read more)