While studying the book of Software Engineering by author Roger Pressman I came across this point about software reengineering , where it is written in the book that if creating documentation is time consuming then it is skipped. Roger Pressman says if there are no significant changes after reengineering then documentation creation is skipped. But if we take example of 'javadoc' and if the javadoc creators just skip the documentation restructuring while new release of java version, just because there is no major change it could be disastrous for the 'javadoc' user. I am confused if this software engineering practice is practical. Can anybody ellaborate and help me understand what Roger Pressman expects here.
7
-
1Being curious can cost a downvote these days....Deepeshkumar– Deepeshkumar2017-10-15 10:38:46 +00:00Commented Oct 15, 2017 at 10:38
-
Yeah your question didn't deserve a downvote without explanationBatavia– Batavia2017-10-15 13:50:05 +00:00Commented Oct 15, 2017 at 13:50
-
I think the point of these remarks is that people are lazy (or being pushed to finish faster) so you can either automate documentation (so it takes no effort) or you have to make it very important. Otherwise people move on to other stufBatavia– Batavia2017-10-15 13:52:10 +00:00Commented Oct 15, 2017 at 13:52
-
I didn't downvote, but: 1. Questions containing words like "fair" are unanswerable unless you can specifically define such words within the context of a practical problem you're facing. 2. We don't know what Roger Pressman was thinking when he wrote his book.Robert Harvey– Robert Harvey2017-10-15 15:39:11 +00:00Commented Oct 15, 2017 at 15:39
-
You might not be able to guess or understand what Roger Pressman was thinking. But some others do answered well.... . Thanks for pointing out my mistakes.Deepeshkumar– Deepeshkumar2017-10-15 15:46:30 +00:00Commented Oct 15, 2017 at 15:46
|
Show 2 more comments
1 Answer
Documentation is more than reference documentation. Keeping Javadoc- or Doxygen-style references up to date is fairly easy because they are written right next to the code.
A lot of documentation lives in completely separate documents. For example, end-user software may have a manual. There may also be internal documents, like architecture overviews, UML diagrams, change request documents, or audit reports.
All of these documents have value. But their value does not always outweigh the cost of updating them after each change. E.g. doing an audit may be very costly, but it may be possible to skip it for minor changes. If the architecture was not changed significantly, there's no need to redo all diagrams. It depends on the chosen development process, on the business priorities, and on the regulatory context which documents need to be updated.
Staying with your Java SDK example, there's not just the Javadoc documentation. The SDK also contains extensive guides and tutorials for specific parts of the language and standard library, e.g. a guide through available Swing GUI widgets. It is likely not necessary to update these for each Java release because the library and the language mostly stay the same.
