Doing Documentation Quickly and Effectively

Pick a Reality

You're busy.

You're drowning in stories.

"It's not important."

The Truth(s)

"It's pointless!"

"Good code explains itself." 🤨

I don't care.

A Possible, Alternative Truth

... you have no idea how to document.

Quick Breakdown

What do I document?

Changelog
Todos
Good commit messages
Architectural decisions
DEVELOPING.md
README.md
Comments

automated/assisted by tooling / manual

The manual stuff

Basic docs

README.md

One way to start writing one

DEVELOPING.md

Don't be a douche.

Comments

Explain the why, not the how.

The automated stuff!

## Changelogs ```bash npm i -g conventional-changelog-cli ``` ```npm { "scripts": { "changelogs": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0" }, "devDependencies": { "leasot": "^7.0.0" } } ```

## Todos ```bash npm i -g leasot ``` ```npm { "scripts": { "todo": "leasot 'src/**/*.js'", "todo-ci": "leasot -x --reporter markdown 'src/**/*.js' > TODO.md" }, "devDependencies": { "leasot": "^7.0.0" } } ```

## Commit messages Read more: https://www.conventionalcommits.org/en/v1.0.0/ ```bash npm i -g husky npm install --save-dev @commitlint/{config-conventional,cli} ``` ```npm { "husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" } } } ```

## Architectural Decision Records (ADRs) Read more: https://github.com/joelparkerhenderson/architecture_decision_record Boilerplate: https://github.com/joelparkerhenderson/architecture_decision_record/blob/master/adr_template_by_michael_nygard.md

```bash # https://github.com/npryce/adr-tools brew install adr-tools adr init doc/architecture/decisions adr new Implement as Unix shell scripts ``` ### How to use them 1. Big feature 2. Impromptu decisions to be documented 3. Decisions after meetings/discussions