JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
0 likes104 views
1) Documentation is important for collaborating on projects and preserving knowledge but can be costly, so finding the right balance is important. 2) There are different types of documentation for different purposes and audiences, from informal communication to more formal specifications and models. 3) Agile documentation practices emphasize creating simple documents iteratively as needed, publishing them for feedback, reusing content, and using basic tools to keep the focus on content over presentation.
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
- 1. Ademar Aguiar University of Porto to document, or not document: that’s the question…
- 11. Software development continuously and iteratively Communicating and sharing knowledge and experience Formalising information Collaborating People needs to talk and read in order to understand requirements, specifications, and other informal artifacts (meeting notes, requirements, draft designs...) with the goal of producing more formal artifacts (code, formal specifications, models...). To collaborate, we need to share information and artifacts. Different kinds of artifacts are typically produced and presented using different tools and environments. Informal and personal communication is usually the best, but sooner or later, you may need to produce documentation in order to preserve, communicate and share the knowledge you have acquired about your project or software system.
- 12. Knowledge acquisition ▪ Most (but not all) knowledge is in the head of experts ▪ therefore it must be shared with non-experts ▪ Experts have vast amounts of knowledge ▪ therefore there is a need to focus on essentials ▪ Each expert doesn't know everything ▪ therefore experts must interact with each other ▪ Experts have a lot of tacit knowledge ▪ therefore they know more than they realize ▪ Experts are very busy and valuable people ▪ therefore capturing techniques must be non-intrusive ▪ Knowledge has a "shelf life” ▪ therefore it evolves, is created, and must be maintained
- 13. Understanding = docs + conversations ▪ Knowledge acquisition requires contents and context. ▪ Knowledge can be partially preserved as documents, but not all. ▪ Understanding the knowledge is the issue. ▪ Understanding needs documentation and conversation. (documents only gathers 15-25% of all the knowledge of complex systems)
- 15. Balancing agility & discipline source:book"BalancingAgilityandDiscipline”,fromBarryBoehmandRichardTurner
- 16. capabilities, communication, knowledge, discipline, self- organization, adaptability, optimization, pace, quality, ROI, predictability, culture, criticality, size, dynamism... practices, documentation, formalities, leadership, roles, artifacts, tools, training, planning, feedback, size the project… Inspect & adapt
- 17. communication, knowledge, quality documentation, formalities, roles, artefacts, tools
- 18. How to document?
- 19. Software documentation ▪ Documentation is good but hard and costly ▪ Every project benefits with good documentation but it has costs, so we need to decide which is the“right dose” of documentation that guarantees the success of our project. ▪ Each project is a case. ▪ Simple and small projects may require few documentation. ▪ For example, for reusable software, good documentation is crucial because nobody reuses what they don’t know, don’t understand, or what seems to be difficult to reuse.
- 22. Agile Modeling
- 23. Configuration Production Organization documents, models, source code usage feedback integrated contents templates, tool setup Maintenance refinements Contents storage processed contents manager author reader metadata tools activity artifacts role role-assignment Usage
- 24. Patterns Target Audiences Documents Creation Cross-References Semantic Consistency Documents Organization Contents Publishing and Presentation Supporting Tools is-related-to patterns helps provides focus requires requires requires supports requires implies requires Target Audiences Documents Creation Cross-References Semantic Consistency Documents Organization Contents Publishing and Presentation Supporting Tools is-related-to patterns is-related-to patterns is-related-tois-related-to patternspatterns helps provides focus requires requires requires supports requires implies requires
- 26. Core practices ▪ Create simple documents, but just simple enough • A minimalist document must be brief, it shouldn’t contain everything, but just the enough information that fulfils its purpose and the intended audience. • The simplicity and understandability of contents must be evaluated by the readers. ▪ Create several documents at once • To represent all the aspects of a system, and to serve all the audiences and purposes, it is often necessary to use different documents, which when edited in parallel and properly cross- referenced help writers on “dumping” their knowledge more effectively, as it avoids to switch contexts.
- 27. Core practices ▪ Publish documents publicly • Publicly available documents, published for everyone to see, supports knowledge transfer, and improves communication and understanding. • The feedback increases and the quality of documents quickly improves. ▪ Document and update only when needed • To be cost-effective, documents should be created and refined iteratively only when needed, not when desired. ▪ Reuse documentation • Reuse contents and structure of existing documentation to improve the productivity and quality of the documentation. • Reusable contents must be modular, closed, and readable in any order.
- 28. Additional practices ▪ Use simple tools • The usage of simple tools help focus more on the contents, rather than on the presentation. ▪ Define and follow documentation standards • Writers must agree and follow a common set of documentation conventions and standards on a project. ▪ Document it, to understand it • To document helps on formalising ideas focused on single aspects, in isolation from many others.
- 30. Internal vs External Documentation ▪ Internal documentation • is limited to low-level, textual explanations, usually included in source code comments; ▪ Higher-level external documentation • capable of capturing the components and connectors of an architecture and the interactions of cooperating classes; • the consistency between external documents and source code can be difficult to maintain as the system evolves over time.
- 31. A lot of documents… private components domain design overview protected view implementation public view user developer maintainer framework overview, snapshots, images implementations type and operation specifications examples cookbooks, recipes design patterns technical and application architecture interface and interaction contracts refinements use cases, scenarios detailed use cases design notebooks collaborations, roles class interfaces abstract concrete contents reference
- 32. Patterns Framework Overview Spiral Cookbook Customizable Points Design Internals Error Recovery Guide Graded Examples Documentation Roadmap Traversable Code Reference Guide is-related-to patterns where to start? first recipe how-to’s errors uses illustrate how it works? code index Framework Overview Spiral Cookbook Customizable Points Design Internals Error Recovery Guide Graded Examples Documentation Roadmap Traversable Code Reference Guide is-related-to patterns is-related-to patterns is-related-tois-related-to patternspatterns where to start? first recipe how-to’s errors uses illustrate how it works? code index
- 33. Example: JUnit
- 34. Tools
- 35. Heterogeneous documents ▪ Software artifacts can be categorized in source code, models, and documents (free text, structured text,...) ▪ Useful external documents often combine contents from different kinds of software artifacts, which are here called heterogeneous software documents.
- 36. Key issues ▪ Heterogeneous software documents issues include: • the preservation of the semantic consistency between the different kinds of contents (such as informal documents and source code); • the lack of appropriate documentation environments; • contents integration; • contents synchronisation. ▪ All these issues have a strong impact on the cost of producing, evolving, and maintaining the documentation.
- 39. Inline of Java source Inline of UML XSDoc Wiki
- 40. Doc-It! - Snipsnap wiki
- 41. Weaki: a weakly typed wiki
- 42. Weaki: key features ▪ Transclusion of code ▪ The inclusion of part or all of an electronic document into one or more other documents by reference ▪ Structure emergence ▪ While editing pages, recurrent common structures will emerge. These structures can at anytime be captured as reusable types. ▪ Homogeneity ▪ Types are wiki pages. All known wiki metaphors are applicable. ▪ Scaffolding ▪ Whenever someone wants to create a new page of a particular type, the wiki automatically fills it with an initial skeleton, derived from that type's structure. ▪ Structured views ▪ Structured viewing filters out content not compliant to the page’s type. This provides a consistent view of every page of the same type.
- 43. Weaki: key features ▪ Content Assist ▪ The creation of new content is assisted with context aware suggestions, while editing a typed page. ▪ Global time labels ▪ Labelling a moment in time. View the entire wiki state at that moment. ▪ Type awareness ▪ Types evolve. Pages evolve. Their level of compliance varies. Awareness of this metric allows balancing evolution vs. type adequacy. ▪ Team awareness ▪ The neighbourhood consists of wiki contributors (authors, editors, even readers) that inhabits the same pages as you. Being aware of who they are, nurtures constructive conversations.
- 44. Weaki for DokuWiki (under development…)
- 46. Ademar Aguiar ademar.aguiar@fe.up.pt to document, or not document? well, it depends… 😎