Documentation Culture

The written word is a very effective way to communicate and has been for many thousands of years of human culture.

Writing documentation is a skill and therefore benefits with practice and regular use.

Writing should be a natural activity that is highly valued as a perminant record of communication.

Personal Journal

For the writer of the journal, there is a feeling of accomplishment as well as a record of challenges they have been facing.

For the rest of the organisations journals highlight

Share Daily Journal

Use the organisation documentation tool to share a daily journal, sharing challenges, lessons learned.

Personal Journal as practice

Writing every day in a journal provides lots of practice in the art of writing and a

Design Journal

Capture design decisions as they are made, indicating all the options considered and why a particular choice was made.

!!! "Clojure Code journal" In expressive languages like Clojure, it is common to capture evolving designs and alternative options in souce code.

Clojure uses the `(comment ,,,)` expression to contain experimental code and keep it separate from production code.  Short design journals may appear at the end of the namespace they belong too.  Longer design journals are defined in their own namespace, often under the `dev` directory.

[:fontawesome-solid-book-open: Practicalli Clojure REPL workflow - Design Journal](https://practical.li/clojure/introduction/repl-workflow/#design-journal){target=_blank .md-button}

Architecture Decison Record

Architecture Decison Record (ADR) captures all the information around a single decision and complements a more general design journal for an engineering team.

Technical writing

Sharing how to write engaging documents that cover the relevant technical detail required for understanding.

Playbooks

Create specific guides to common tasks for the team, to share collective knowledge and greatly increase effectiveness across the organisation.