This document discusses living documentation, which aims to keep documentation up-to-date by storing it alongside the code or system it documents. Key principles of living documentation include keeping it reliable, low-effort to maintain, collaborative, and insightful. Examples given include self-documenting code through naming conventions and comments, as well as automatically generating documentation from code. The goal is to make documentation maintenance fun and simple so it is sustained over time as a project evolves.

1. LIVING DOCUMENTATION
Mini-workshop

2. https://leanpub.com/livingdocumentation
Cyrille Marraine

3. “When comes the time to do documentation,
members of the team select some elements of
knowledge of what has been done and perform a
Manual Transcription.

4. “The documentation quickly becomes obsolete, and
you end up with an incomplete documentation
that you cannot trust.

5. FROM THE “MANIFESTO FOR AGILE SOFTWARE DEVELOPMENT ”
We are uncovering better ways of developing software by doing
it and helping others do it. Through this work we have come to
value:
➤ Working software over comprehensive documentation
http://agilemanifesto.org/

6. “Each instruction typed in a programming language
is a decision.

7. PRINCIPLES
➤ Knowledge that is of interest for a long period of
time deserves to be documented.
➤ Knowledge that is of interest to a large number of
people deserves to be documented.
➤ Knowledge that is valuable or critical may also need
to be documented.

8. “The best place to store documentation is on the
documented thing itself.

9. “In a software project most of the knowledge is
present in some form somewhere in the artefacts.

10. EXAMPLES
➤ Self-documenting code and Clean Code practices, including:
➤ Class and method naming
➤ Types
➤ Annotations that add knowledge to elements of the
programming language
➤ Javadoc comments on public interfaces, classes and main
methods
➤ Folder organization, modules and submodules
decomposition and naming

11. “The key concern to keep in mind is the cost of
evolution and maintenance of the documentation.

13. PRINCIPLES OF LIVING DOCUMENTATION
➤ Reliable
➤ Low-Effort
➤ Collaborative
➤ Insightful

14. “If it’s not fun, you’ll not want to do it so often and
the practice will progressively disappear.

15. LET THE WORKSHOP BEGIN!
➤ Explore living documentation practices, for example in:
➤ “Part 2: Living documentation” of the book, or
➤ README.md of the sandbox project
➤ Try to implement/automate something as a Proof-of-Concept
➤ Do the most simple thing to make it work
➤ Homework: make it nice & reusable :)