Documentation - Code, Architecture

[anitsh]

Documentation

The devil is the details. - Fact

"Documentation is a love letter that you write to your future self." - Damian Conway

"History helps us become, history helps us evolve, history let's us never forget." - Unknown

Resource

• [ ] https://medium.com/nick-tune-tech-strategy-blog/self-documenting-architecture-80c8c2429cb8
• [ ] http://agilemodeling.com/artifacts: Resources on concepts for documentation.
• [ ] https://betterprogramming.pub/solutions-architect-tips-the-5-types-of-architecture-diagrams-eb0c11996f9e
• [ ] https://adr.github.io
• [ ] https://opensource.com/article/20/4/documentation
• [ ] https://www.thoughtworks.com/insights/blog/four-goals-agile-documentation-part-one
• [ ] https://www.thoughtworks.com/insights/blog/four-goals-agile-documentation-part-two
• [ ] https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• [ ] "Diagrams as code 2.0" Talk slides by Simon Brown - https://t.co/mxW7v8ZrJj?amp=1
• [ ] https://betterprogramming.pub/bring-back-the-rfcs-afda4f332ee RFC - request for change, for architectural documentation
• [ ] https://www.redhat.com/architect/diagramming-tools-cloud-infrastructure - 6 architectural diagramming tools for cloud infrastructure

Doxygen

• [ ] https://en.wikipedia.org/wiki/Doxygen
• [ ] https://developer.ibm.com/technologies/systems/articles/au-learningdoxygen
• [ ] https://www.cs.cmu.edu/~410/doc/doxygen.html

[anitsh]

Code Documentation

“Code is more often read than written.”
— Guido van Rossum

“It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.“
— Daniele Procida

“Code tells you how; Comments tell you why.”
— Jeff Atwood (aka Coding Horror)

Resource:

• Python Documentation
  • https://devguide.python.org/documenting/
  • https://realpython.com/documenting-python-code

[anitsh]

Architecture Documentation

• [ ] https://adr.github.io Architecture Decision Records
• [ ] https://c4model.com The C4 model for visualising software architecture - Context, Containers, Components, and Code

[anitsh]

Tools: https://diagrams.net, https://excalidraw.com