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.
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)
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.
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
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.
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.