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