Precise Documentation: The Key To Better Software David Lorge Parnas - PowerPoint PPT Presentation

Middle Road Software, Inc. Precise Documentation: The Key To Better Software David Lorge Parnas Abstract The prime cause of the sorry “state of the art” in software development is our failure to produce good design documentation. Poor documentation causes many errors and reduces efficiency in every phase of a software product’s development and use. Better software documentation methods, and the resulting better documentation, would revolutionize the software field. Most software developers, believe that “documentation” refers to a collection of wordy, unstructured, introductory descriptions occupying thousands of pages; they think of text that nobody wanted to write and nobody trusts. In contrast, Engineers in more traditional disciplines, think of precise blueprints, circuit diagrams, and mathematical specifications of component properties; they recognize that documentation is their main design medium. Software developers do not know how to produce precise documents for software and consider documentation to be an afterthought. In fact, it should represent forethought not afterthought. Among the benefits of better documentation would be: easier reuse of old designs, better communication about requirements, more effective design reviews, easier integration of separately written modules, more effective code inspection, more effective testing, and and increased efficiency when making corrections and improvements. This talk explains how developers can produce and use precise software documentation and illustrates the methods with several examples. David Parnas 1/58 Zurich documentation slides.pages

Middle Road Software, Inc. 1. Documentation: a perpetually unpopular topic ------------ 3 30. Relation REQ -------------------------------------------------- 32 2. Why Real Improvement is Difficult --------------------------- 4 31. Experience and examples: Requirements ------------------ 33 3. Dilbert Knows that documentation is important. ---------- 5 32. Interfaces ------------------------------------------------------ 34 4. Programming vs. software design --------------------------- 6 33. Surprising Observations about Interfaces. ----------------- 35 5. What Is Meant by “Document” ------------------------------- 7 34. Software component interface documents ----------------- 36 6. A Preliminary Example: Dell Keyboard Checker ----------- 8 35. Part I of Clock Interface Document ------------------------- 37 7. Requirements for Keyboard Checker ----------------------- 9 36. Part II of Clock Interface Document ------------------------ 38 8. No Theoretical Advantage ------------------------------------ 10 37. Extract from Module Interface Document ------------------ 39 9. Completeness and Consistency ----------------------------- 11 38. Program function documents -------------------------------- 40 10. Are computer programs self-documenting? --------------- 12 39. Example of Program-Function Table ------------------------ 41 11. Internal documentation vs. separate documents ---------- 13 40. Program-Function for a Poor (real) Program --------------- 42 12. Models vs. documents ---------------------------------------- 14 41. Subtables for Nuclear Plant Code --------------------------- 43 13. Design documents vs. introductory documentation ------- 15 42. Module internal design documents ------------------------- 44 14. Specifications vs. other descriptions (1) -------------------- 16 43. Checking an Internal Design --------------------------------- 45 15. Specifications vs. other descriptions (2) -------------------- 17 44. Additional documents ---------------------------------------- 46 16. Extracted documents ----------------------------------------- 18 45. Tabular expressions for documentation -------------------- 47 17. Documents Are Not Programs ------------------------------- 19 46. There are many forms of tabular expressions. ------------- 48 18. Roles played by documents in development - 1 ----------- 20 47. Tables like this Can be Found on the Internet -------------- 49 19. Roles played by documents in development - 2 ----------- 21 48. This says the same thing ------------------------------------- 50 20. Costs and benefits of software documentation ------------ 22 49. This Too is A Mathematical Expression --------------------- 51 21. The most important software design documents ---------- 23 50. A Circular Table ------------------------------------------------ 52 22. Considering readers and writers ---------------------------- 24 51. Is this Different from “Formal Methods” -------------------- 53 23. What makes design documentation good? ---------------- 25 52. The Bottom Lines: -------------------------------------------- 54 24. Documents and mathematics -------------------------------- 26 53. Management’s Role in Document Driven Design ---------- 55 25. Requirements Documentation ------------------------------- 27 54. Research Problems ------------------------------------------- 56 26. The two-variable model for requirements documentation 28 55. Summary and Outlook ---------------------------------------- 57 27. Notation -------------------------------------------------------- 29 56. Thank You for Staying ---------------------------------------- 58 28. Nondeterminism ---------------------------------------------- 30 29. Relation NAT --------------------------------------------------- 31 David Lorge Parnas 2/58 Zurich documentation slides.pages

Middle Road Software, Inc. Documentation: A Perpetually Unpopular Topic Software documentation is disliked by almost everyone. • Program developers don’t want to prepare documentation. • User documentation is often left to technical writers who do not necessarily know all the details. Their documents are often initially incorrect, inconsistent and incomplete. • The intended readers find the documentation to be poorly organized, poorly prepared and unreliable; they do not want to use it. Most prefer “try it and see” or “look at the code ” to relying on documentation. • User documentation is often displaced by “help” systems because it is hard to find the details that are sought in conventional documentation. Unfortunately, the “help” system only answers a set of frequently occurring questions; it is usually incomplete and redundant. Those with an unusual question don’t get much help. • Computer Science researchers do not see software documentation as a research topic They can see no mathematics, no algorithms, etc.. These factors feed each other in a vicious cycle. Bad documentation is not used and does not get improved. David Lorge Parnas 3/58 Zurich documentation slides.pages

Middle Road Software, Inc. Why Real Improvement Is Difficult “Nobody” does it that way. • “Nobody” builds really good software (error free, easily maintained) We don’t have time to write documents that nobody reads. • “Never have time at the start, always have time at the end” (B.O. Evans) “I have no idea how to do that” (Ph.D. developer, author) • Nobody taught you how! Finally, Dilbert’s view on making real changes: • Ideas that would change the way we work can be very threatening. David Lorge Parnas 4/58 Zurich documentation slides.pages

Middle Road Software, Inc. Dilbert Knows That Documentation Is Important. When people leave, knowledge leaves with them. David Lorge Parnas 5/58 Zurich documentation slides.pages

Middle Road Software, Inc. Programming Vs. Software Design “Software design” is not just another name for programming. Programming is only a small part of software development. • “Software” refers to “ a program or set of programs written by one group of people for repeated use by another group of people ” 1 . This is fundamentally different from producing a program for a single use, or for your own use. • When producing a program for your own use, you can expect the user to understand the program and to know how to use it. There is no need to prepare manuals that explains what parameters mean, the format of the input, or compatibility issues. All are required when preparing a program that will be used by strangers. • When producing a program for a single use, there is no need to design a program that will be easily maintained in several versions and no need to describe the design to those who will have to change it. It is the differences between software development and programming (multi-person involvement, multi-version use) that make documentation important for software development. 1 Brian Randell was the first to point this out. David Lorge Parnas 6/58 Zurich documentation slides.pages