Rational Documentation in Software Engineering

1. Parnas and Clements:A Rational Design Process: How and Why to Fake It • IEEE TSE, vol SE-12, no. 2, Feb. 1986 • The Goal of Software Software Engineering: A Rational Design Process • What is a rational agent? • Considers all choices thoroughly and correctly • Perfectly documents all results • Sounds great, but… Parnas and Clement 86

2. There Is No Rational Agent • Lots of reasons: • Customers don’t know what they want, • don’t know everything we need in advance, • we’re only human, • external change, • preconceived notions, • economic limitations… • the list goes on • We abandon “rational” design. . . Parnas and Clement 86

3. Why Document? • Requirements: User <-> Developer communication, estimation, turnover insurance, establishing desired behavior • Module: Work assignments, cross-module-implementer communication, module connection overview • Future: Maintainers need a way to learn the system • Others, too Parnas and Clement 86

4. What’s Wrong With Most Documentation? • Poor Organization (mostly “stream of consciousness” or “stream of execution”) • Both nearly impossible to find anything when you look for something • Boring prose • Confusing/inconsistent terminology • Myopic viewpoint (too close to system when written) • . . . wouldn’t it be nice to have the “rational” documentation? Parnas and Clement 86

5. Fake It! • Imagine yourself as the ideal agent, and write the documentation you would have produced • Design the documentation • Separation of concerns: One system aspect for one section, no more, no less • Document what is important, with the addition of rejected design decisions • Justification: Even Mathematics, the very definition of “rational”, works this way: Results preferred over precise history of an idea Parnas and Clement 86

6. Conclusions • Result: Useful documentation that can be produced in the real world • Unlike other papers presented, these ideas are still revolutionary • Unfortunately, few people do this. (In fact, people are often shocked if you do.) • Tells us what we want, but not how to get it Parnas and Clement 86

7. Related 1: User’s Manual as Requirements Specification • Berry, Daudjee, et al. May 2001 • Summary: The desirable properties of a users manual are the same as the desirable properties of a requirements specification. • So write the Requirements Specification in the form of a User’s Manual Berry, Daudjee, et al. 2001

8. What Properties? • Requirements elicitation • Communication • Client can understand user’s manuals where they may not understand other standard requirements documents • Programmers can see exactly what the requirements are calling for • Validation • Customer’s ideas versus designer’s ideas • Code versus features Berry, Daudjee, et al. 2001

9. Why User’s Manual? • To write one, one must have: • A complete understanding of each use the system will be put to (use cases) • We can write one for each type of user, to ensure feature coverage (developer vs. user vs. administrator) • Provides scenarios which can be used as test cases • Enforces user-centered design (can’t write manual to the developers) • Exposes ambiguities Berry, Daudjee, et al. 2001

10. Related 2: Software Documents: Concepts and Tools • Jim Welsh, Jun Han in Software - Concepts and Tools (vo15, no. 1, 1994) • Summary: all results of the software engineering process can be considered as documents. • Source Code: a carefully specified formal document that can be executed by a computer. Welsh and Han 94

11. Ideal Development Environment • Set of Documents focusing on required features. • Set of Tools help us maintain the documents (i.e. consistency across versions): • starting with the loosest, informal specifications. • moving toward fully formal specifications. • ending up with actual source code (literate program) Welsh and Han 94

12. Welsh and Han 94

13. Parnas and Clement 86

14. Parnas and Clement 86

15. Parnas and Clement 86

16. Tools: Rational Assistants • verification of code • tie together the original specification, the formal specification, and the actual code. • improve the ease of formally validating code. • Improve level of connectivity • automated consistency checks: e.g. propagate a variable name change across all code. • analyze certain changes. Welsh and Han 94

17. Extending Parnas’s work • A concrete way to achieve the goals Parnas and Clements lay out. • By improving our tools, we improve our ability to create coherent documents. • contain all of the information we may be interested. • from the start through to the finish. • If the proposed "Software Documents" existed, it would be much easier to produce "Rational Documentation." Welsh and Han 94

18. Related 3: A Development Method for Multiagent Systems • J. Lind 2000 • Summary: a pragmatic process model for the development of multiagent systems based on the combination of standard SE techniques using 7 views. • The approach applied and refined successfully in various industrial research projects. J. Lind 2000

19. MASSIVE view • MASSIVE: MultiAgent SystemSInterative View Engineering J. Lind 2000

20. View-oriented Modeling? • “View" is a projection of the root model of the system with only a certain type of information in it. • Projection: is analogous with geometric projection of multi-dimensional objects into lower dimensions. • A “Model” for the creation of multiagent systems based on the idea of creating and using seven "views" on the system. J. Lind 2000

21. Iterative View Engineering • How to create the views and models? • Combines: • Roundtrip Engineering (Balzert 98) • Iterative Enhancement (Basili and Turner 75) • Using IE as a repeated subprocess to extend RE • Adding IE steps to the creation of the model, the implementation • Adding trips around the whole process J. Lind 2000

22. Extending Parnas’s work • adding to the corpus of work on abstract documentation processes. • using the observations Parnas and Clements made about rational design processes. • “any specification is initially incomplete” • Parnas and Clements provided useful ideas for the difficult problem of developing documentation, and software. J. Lind 2000

23. Uncited: A Pragmatic Approach to Software Documentation • Klaus Didrich, Torsten Klein 1996 • Summary: The author extends Literate Programming to work in more situations then traditional Literate Program Didrich Klein 1996

24. Quick Sidebar: What is Literate Programming? • Developed by Knuth in his paper “Literate Programming”, The Computer Journal, 27(2):97-111, 1984 • Principle: Focus on documentation over code, write both in same file • Uses a tool to construct source code files from the doc/code hybrid files Didrich, Klein 1996

25. Dosfop Diagram Didrich Klein 1996

26. Problems • A language on top of a language increases complexity and learning time • Languages have changed • Need for code re-ordering reduced by increased granularity of OO and functional programming • More real programming modules work across multiple files, which original Literate Programming specs handled poorly Didrich Klein 1996

27. Why Should This Paper Cite Parnas? • It must be possible to integrate quick-and-dirty code and only later document it • This is a way of faking a rational design process Didrich Klein 1996