agile doc libs

coders perspective

• coders favor coding over docs
• agile favors delivery over docs
• how do i convey the architecture
• a picture is worth a thousand words
• spent a lot of time in Visio on layouts, etc
• my design has become outdated
• where is the confluence / wiki page
• requirements, etc scattered
• just show me what has changed

client perspective

• where are the requirements
• where is the code
• how does the service work
• acceptance for production
• service updated - docs old
• prod issue - how to find test gap

happy place

• simple design & code
• code & docs together
• docs consistent with code
• all docs in one place
• versions managed by vcs
• published for easy access

References

https://github.com/davejwilson/agile-doc-libs

• https://github.com/swagger-api
• http://asciidoctor.org/
• https://github.com/gboersma/uml-java-doclet
• http://plantuml.com/
• https://eclipse.org/aspectj/
• https://github.com/jeluard/maven-plantuml-plugin
• https://projectlombok.org/
• https://maven.apache.org/plugins/maven-site-plugin/