Living documentation mini-workshop

LIVING DOCUMENTATIONMini-workshop

https://leanpub.com/livingdocumentation

Cyrille Marraine

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

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

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/

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

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.

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

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

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

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

PRINCIPLES OF LIVING DOCUMENTATION

➤ Reliable

➤ Low-Effort

➤ Collaborative

➤ Insightful

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

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