Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Ademar Aguiar
University of Porto
to document, or not document:
that’s the question…
Wikis, WikiSym, OpenSym
Software development
continuously and iteratively
Communicating and sharing
knowledge and experience
Formalising 

informa...
Knowledge acquisition
▪ Most (but not all) knowledge is in the head of experts

▪ therefore it must be shared with non-exp...
Understanding = docs + conversations
▪ Knowledge acquisition requires contents and context.

▪ Knowledge can be partially ...
Knowledge evolution spiral
Balancing agility & discipline
source:book"BalancingAgilityandDiscipline”,fromBarryBoehmandRichardTurner
capabilities, communication, knowledge, discipline, self-
organization, adaptability, optimization, pace, quality, ROI,
pr...
communication, knowledge, quality
documentation, formalities, roles, artefacts, tools
How to document?
Software documentation
▪ Documentation is good but hard and costly

▪ Every project benefits with good documentation but i...
Minimalist Instruction
Agile Modeling
Configuration Production Organization
documents,
models,
source code
usage
feedback
integrated
contents
templates,
tool se...
Patterns
Target
Audiences
Documents
Creation
Cross-References
Semantic
Consistency
Documents
Organization
Contents Publish...
Agile documentation
Core practices
▪ Create simple documents, but just simple enough

• A minimalist document must be brief, it shouldn’t cont...
Core practices
▪ Publish documents publicly

• Publicly available documents, published for everyone to see, supports
knowl...
Additional practices
▪ Use simple tools

• The usage of simple tools help focus more on the contents, rather
than on the p...
What to document?
Internal vs External Documentation
▪ Internal documentation 

• is limited to low-level, textual explanations, usually inc...
A lot of documents…
private
components
domain
design
overview
protected view
implementation
public view
user
developer
mai...
Patterns
Framework
Overview
Spiral
Cookbook
Customizable
Points
Design
Internals
Error Recovery
Guide
Graded
Examples
Docu...
Example: JUnit
Tools
Heterogeneous documents
▪ Software artifacts can be categorized in source code,
models, and documents (free text, structur...
Key issues
▪ Heterogeneous software documents issues include:

• the preservation of the semantic consistency between
the ...
Single source approach
Multiple source approach
Inline of Java source
Inline of UML
XSDoc Wiki
Doc-It! - Snipsnap wiki
Weaki: a weakly typed wiki
Weaki: key features
▪ Transclusion of code

▪ The inclusion of part or all of an electronic document into one or more
othe...
Weaki: key features
▪ Content Assist

▪ The creation of new content is assisted with context aware
suggestions, while edit...
Weaki for DokuWiki (under development…)
Dzięki!
Obrigado!
Ademar Aguiar
ademar.aguiar@fe.up.pt
to document, or not document?
well, it depends… 😎
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question
Upcoming SlideShare
Loading in …5
×

JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question

79 views

Published on

Agile processes often consider “to document” as a very expensive activity, which is often true, indeed, and also unnecessary, which is not always true, however.

To better communicate and preserve all the knowledge about a software system, agile processes suggest practices such as simple design, pair programming, and collective code ownership, to name only a few.

While the extreme practice of “not document” can lead to success in many cases, this is not always true for complex software products, where there is a lot of global knowledge and system understanding that is impossible to capture internally in source code.

In this presentation, we will outline a set of practices, patterns, and tools to support an agile way of minimally documenting the global understanding of complex software systems, from source code to high level design and how to (re)use.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

JDD 2016 - Ademar Aguiar - To Document Or Not Document - That Is The Question

  1. 1. Ademar Aguiar University of Porto to document, or not document: that’s the question…
  2. 2. Wikis, WikiSym, OpenSym
  3. 3. 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.
  4. 4. 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
  5. 5. 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)
  6. 6. Knowledge evolution spiral
  7. 7. Balancing agility & discipline source:book"BalancingAgilityandDiscipline”,fromBarryBoehmandRichardTurner
  8. 8. 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
  9. 9. communication, knowledge, quality documentation, formalities, roles, artefacts, tools
  10. 10. How to document?
  11. 11. 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.
  12. 12. Minimalist Instruction
  13. 13. Agile Modeling
  14. 14. 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
  15. 15. 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
  16. 16. Agile documentation
  17. 17. 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.
  18. 18. 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.
  19. 19. 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.
  20. 20. What to document?
  21. 21. 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.
  22. 22. 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
  23. 23. 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
  24. 24. Example: JUnit
  25. 25. Tools
  26. 26. 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.
  27. 27. 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.
  28. 28. Single source approach
  29. 29. Multiple source approach
  30. 30. Inline of Java source Inline of UML XSDoc Wiki
  31. 31. Doc-It! - Snipsnap wiki
  32. 32. Weaki: a weakly typed wiki
  33. 33. 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.
  34. 34. 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.
  35. 35. Weaki for DokuWiki (under development…)
  36. 36. Dzięki! Obrigado!
  37. 37. Ademar Aguiar ademar.aguiar@fe.up.pt to document, or not document? well, it depends… 😎

×