2

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.

  • 1
    Being curious can cost a downvote these days.... – Deepeshkumar Oct 15 '17 at 10:38
  • Yeah your question didn't deserve a downvote without explanation – Batavia Oct 15 '17 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 stuf – Batavia Oct 15 '17 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 Oct 15 '17 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 Oct 15 '17 at 15:46
5

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.