Software Explanation Document

In summary, Many organizations and companies do not publish precise, well-written Software Explanation Documents that explain how a program works. This lack of documentation can lead to wasted time and money in software maintenance and hinders the ability to judge the quality of a program. A Program Explanation Document should be the only thing delivered when a program is created, and it should contain explicit and detailed information about the program's design decisions and functionality. Comments are not sufficient for understanding a program and can lead to difficulties in maintenance, especially when the original programmer is no longer available. Real Programmers value proper documentation and do not rely on comments or compilers to understand a program.
  • #1
oldtobor
132
0
In software maintenance, I have noticed that very few organizations and companies publish a precise well written Software Explanation Document to explain exactly and in a very well written way how thousand lines program work.

It is amazing that of all the documents that are written, none of them tell a programmer exactly how the lines of code really work, as if the real working of the code is intentionally left as guess work. I have seen this in very top class professional programs, I bet even NASA and military software programs never really have a Software Explanation Document that can tell a maintenance programmer exactly how the entire program works and all the details necessary to then modify it. Why is this so ? Software maintenance costs a huge amount of money and time and there is no real quality assurance possible without a complete and very detailed written explanation of how a program works.

Actually if an organization needs a program, the only real thing that must be and should be delivered, is only the Software Explanation Document. If any programmer reading and studying this documnet cannot understand it well, then the software can be considered as not having been delivered at all and should not even be paid for until there is this precise document to back it up.

How is it that after decades of software research companies simply don't deliver the most important single document that a maintenance group needs ? Aside from the fact that the program can be studied and all the design decisions can be judged upon giving the buying organization its money's worth and the power to really judge a program.

I find it incredible that in this day and age almost all companies still have to waste an enormous amount of time to figure out how programs work, when it could have been forced upon from the very beginning. Software "engineering" still has a long way to go until a Software Explanation Document doesn't become the real PRODUCT that should be delivered.
 
Engineering news on Phys.org
  • #2
Actually to be even more precise the name of the document should be:

PROGRAM EXPLANATION DOCUMENT so as to pinpoint down exactly what is really needed to understand and eventually change a program written previously by another group.

I find it very primitive that the knowledge embedded in programs must be hidden, must belong to those who wrote the program, and when they are gone the embedded knowledge goes away too. In some cases even the original programmer can't remember what on Earth he did and how the program works after some time!

I think the "comments" method of writing comments next to lines is another very primitive system, that was maybe ok a couple of decades ago (and probably not even then) but not today. Each line, each group of lines, all the design decisions, all the relevant information must be explicitly written out, not short cutted like in comments, not guessed out, but must be explained with the upmost precision. This is the only real tool that software and software engineering have to increase productivity and to start progressing like other engineering disciplines have.
 
  • #3
Real Programmers don't use comments.

If it was hard to write, it should be hard to read.

My favourite was an assembler program with the solitary comment "START"...
 
  • #4
Real Programmers don't use compilers.
OCO (object code only) is the way to go.

[Rant]Salesmen have been pushing documentation snake-oil since the dawn of computing.
The problem is that if your PROGRAM EXPLANATION DOCUMENT did what you wanted it to, then you could just compile that. It would be the program. [/rant]
 
  • #5
zeitghost said:
Real Programmers don't use comments.

If it was hard to write, it should be hard to read.

My favourite was an assembler program with the solitary comment "START"...

That's a load of crap. One of the first things I learned in my very first computer science class was the importance of proper comments.

What if the programmer got hit by a taxi after he finished his uncommented program which was very complicated to create for whatever reason and another programmer had to come in and try and figure out what he was thinking? A lot of wasted time which leads to wasted money.

Granted the comments must be meaningful and are not needed for obvious things.

CS
 
  • #6
I always commented source code. It didn't get into the compiled distributed applications, but comments were always in the original code. This make it possible for some one other than myself (or even myself, after a time) to make needed modifications without parsing all the code to find out where the changes needed to be made.
 
  • #7
stewartcs said:
That's a load of crap. One of the first things I learned in my very first computer science class was the importance of proper comments.

What if the programmer got hit by a taxi after he finished his uncommented program which was very complicated to create for whatever reason and another programmer had to come in and try and figure out what he was thinking? A lot of wasted time which leads to wasted money.

Granted the comments must be meaningful and are not needed for obvious things.

CS

Crap it may well be... it was an interesting program to maintain, since everyone who knew how it worked had left.

I was the guy who had to modify it to do what I wanted it to do...

You've not met many Real Programmers then, have you... :biggrin:

Then again, I had the source, it's even more difficult to modify the executable by patching the binary.
 

What is a "Software Explanation Document"?

A "Software Explanation Document" is a detailed written description of the purpose, functionality, and design of a software program. It provides a comprehensive overview of the software and allows readers to gain a better understanding of its features and capabilities.

Why is a "Software Explanation Document" important?

A "Software Explanation Document" is important because it helps users, stakeholders, and developers understand the software and its intended use. It also serves as a reference guide for troubleshooting issues and making future improvements.

What information should be included in a "Software Explanation Document"?

The information included in a "Software Explanation Document" may vary, but typically it should contain an overview of the software, its features and functionalities, system requirements, installation instructions, user guidelines, and any relevant diagrams or visuals to aid in understanding.

Who is the target audience for a "Software Explanation Document"?

The target audience for a "Software Explanation Document" includes software users, developers, project managers, and other stakeholders involved in the creation and use of the software. It may also be useful for potential investors or clients who are interested in understanding the software's capabilities.

How often should a "Software Explanation Document" be updated?

A "Software Explanation Document" should be updated whenever there are significant changes to the software, such as new features or updates. This ensures that the document remains accurate and relevant to the current version of the software.

Similar threads

  • Quantum Interpretations and Foundations
6
Replies
204
Views
7K
  • Programming and Computer Science
Replies
29
Views
2K
  • Programming and Computer Science
Replies
7
Views
1K
  • Set Theory, Logic, Probability, Statistics
Replies
7
Views
1K
  • Electrical Engineering
Replies
18
Views
1K
  • Programming and Computer Science
Replies
16
Views
1K
  • Programming and Computer Science
Replies
14
Views
1K
  • General Discussion
Replies
9
Views
1K
Replies
23
Views
3K
  • Programming and Computer Science
Replies
10
Views
1K
Back
Top