living documentation mini-workshop
TRANSCRIPT
LIVING DOCUMENTATIONMini-workshop
“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 :)