Documenation of software code:need of time

[rajanjoshe]

Audio visual documentation of software: Need of time.
Dear all,
Every time I have to work on documentation of software, I always beat my head and search on Google if there is any effective documentation tool available. After doing some study and observation, I want to share my opinion with you by mean of this article.

When to start design of software?
Designing of software is inevitable part of any project and start when any project starts, provided developer knows all requirements and are clear to them. Once design is completed and you have documented it, developer can start writing the code(if he has all resources like compiler and debugger available ) as per design. Once written code is tested and found as per requirement a project should be declared as completed.

Then where it goes wrong. Why we feel documentation process tedious?
It is because developer always fail to visualize 100% requirements. Study says requirements get evolved the way project starts and take shape. So whatever we design needed to be reviewed and re-tuned over time and time to meet challenges and customer’s expectation. So design documentation never get completed in one go.

Difference in designing and documenting the design.
In the process of refining the design as per the changing requirements many times it happens that all changed requirements does not get reflected in design document. This always happen with customized project where one has to delivered exactly what customer wants. These requirements sometimes goes out of theme as customer changes some of the requirements on fly. Developer somehow manage to add patch in software but probability of those patches to be reflected in design documents are lessen.
So when project start there is always a need to take call that when to start fool proof design document? Does tool which developer using provide smoothness so that end level changes can be easily get reflected in design. If not then one can go with rough design document on rough papers and then after the end of testing developer can prepare design document using design tool. This method can save tremendous efforts that developer is putting in updating the design documentation.

Does software design document covers 100% details?
There are two types making a design document. First is logical design document which only covers theme or logic upon which you whole software is laid which does not cover all other coding details and design flow. And second is programmatic design document which only indicate software flow but never tells underlying theme or logic behind writing piece of software. There are many software tools available which convert your code into flowchart no need to spend extra effort on it.
It means just preparing logical design document going to end the problem, right? But even then how many times it happens that newly joined developer has to do some reverse engineering on software code (which has been written by x employee) to know what piece of code has been written even when design document of that software code is available?
It happen because no design document covers 100% details of code. I don’t find any such software tool and then it comes to my mind why we not making audiovisual documentary on code which will tell how piece of code is working with diagrams examples, describing functionality of a function or a variable or a macro, it self in code in developer’s own voice.
Advantages:
1) Every minute details will be covered as documentary will be just like a seminar where developer is explaining software code in all details.
2) One can show logical data along with software data flow for effectiveness.
3) Time required to view audio visual documentation is less than that textual and flowchart based design tool.
4) Improve developer’s presentation skills.
5) Remove burden of comments given in code. The comment part can be explained in audio-visual documentation very well.

Challenges:
1) Memory requirement of such audio-visual document can be maximum.
2) There is no such tool which allow audio-visual documentation of software so editing such documents will be difficult, specially in case of more version of software created.
3) Such documentation is difficult to upload on repository or may require larger space.
4) Need to find media format which consumes less memory storage.

Remedies:1) I used wink software(freely available) which generate swf/exe file which consume very low memory. You can also select frame capture rate to minimize storage. 2 frames/seconds are sufficient.

2)If you have large audio-visual documentation then convert it in low data format like(MPEG4-10fps-128x96-AAC-*3gp)
To convert in such media format one can use freecorder software tool which is freely available.

So may I know what all you think about it. Are you all agree that audiovisual documentation is need of time? Please vote your answer and give your valuable feedback.

 

[sky_123]

Documentation occurs on different levels.

I think in many organizations Engineers already prepare audio-visual recordings/presentations to share their knowledge on a certain topic or a certain part of the design of the product they are working on.
These are stored in archives so that newcomers can spend time learning.

However, it's no replacement for conventional "documentation" (i.e. something like MS Word documents) and as you say, requirements and design, should be captured (high and low level), meetings, etc. Tools are used for drawing up flows etc., but many organizations
allow flexibility there; as long as it is adequately captured, and pasted into the appropriate Word document. It certainly could be an AV
file attachment in theory if needed, although I've never seen it.
Generating code from tools, comments in code, etc., is a yet another different level of documentation. Again, organizations have rules on how they
expect this to occur, and code gets reviewed so that one can't take shortcuts. Anyway, this is just my individual experience, and everything can
be improved in theory.

 

[rajanjoshe]

Documentation occurs on different levels.

I think in many organizations Engineers already prepare audio-visual recordings/presentations to share their knowledge on a certain topic or a certain part of the design of the product they are working on.
These are stored in archives so that newcomers can spend time learning.

However, it's no replacement for conventional "documentation" (i.e. something like MS Word documents) and as you say, requirements and design, should be captured (high and low level), meetings, etc. Tools are used for drawing up flows etc., but many organizations
allow flexibility there; as long as it is adequately captured, and pasted into the appropriate Word document. It certainly could be an AV
file attachment in theory if needed, although I've never seen it.
Generating code from tools, comments in code, etc., is a yet another different level of documentation. Again, organizations have rules on how they
expect this to occur, and code gets reviewed so that one can't take shortcuts. Anyway, this is just my individual experience, and everything can
be improved in theory.

"I think in many organizations Engineers already prepare audio-visual recordings/presentations to share their knowledge on a certain topic or a certain part of the design of the product they are working on.
These are stored in archives so that newcomers can spend time learning."
Rajan: What you are saying is right but certain audio-visual documentation is restricted to the concept and not meant for code.There are certain application level projects in embedded system also where code is written according to customer's requirement and there is no clear concept behind it.My suggestion is every line in the code should be illustrated why it is written for.We do it by means of comments but comment is not sufficient to understand code.

I am not restricting other means of textual documentation but does they really cover all information.They may cover the theme but again as i said in customized project certain things get implemented out of theme and no where reflected.This will restrict those engineers who purposefully hide important information in textual documentation by making it vague.Or those information never get documented.

We do audiovisual documentation of concept on same ground i wanted to suggest to make similar documentation for written c code.
Again I am not restricting to make other means of documentation but you can do it without using tool like say UML raphsody.
Why we are making passive time consuming documentation which do not reveal all the information to the new engineer.

Would you take a call and tell me how much time a new engineer let it be fresher or experienced take to be productive when he join new domain he never worked on it.Where design/documentation is served in the form flowchart/UML or any textual means?