[afarrell]

1. Start With Why -- Make sure you know the audience for anything you write.

2. For developers, Default to markdown and easily-updatable diagrams (like mermaid.js).

3. Put docs as close to the Point of Action as you can so that someone can notice if they are out-of-date. Like putting your keys on a hook by the door.