Lead with documentation

As I’ve been refining my approach to work, a phrase has been sticking in my mind:

Lead with documentation

What this means in practice is when I start working on anything that requires a little up front thought, architecture, or planning, the first thing I do is open up the documentation for the project and start writing. If collaboration/discussion is required, I open a pull request to facilitate discussion. However, the approach is still documented in the repo files, not in the PR, Github issue, etc.

This is very different than how most people work, but I’m finding it enjoyable and productive. It is taking effort to switch, as I still tend to put too much documentation in Github issues. Old habits die hard and change takes time.

For this approach to be effective, documentation needs to be frictionless. For me, this means Markdown – preferably in the same repo as the design/source files. Then it is easy to edit code and docs in the same editor.

Some of the benefits to this approach:

  1. when you are done with a task, the documentation is already done. Doing documentation after the fact is a rather distasteful task. However, if it s done before the task, it is very engaging.
  2. it helps you think. As Leslie Lamport says, To think, you have to write. If you’re thinking without writing, you only think you’re thinking.
  3. documentation does not become stale, outdated, and useless.
1 Like

Upon reflection, it is ironic that I should have written this first in the tmpdir handbook where it would become part of a long-living, permanent document, and then linked/discussed it here. Fixed now. Change is hard.

1 Like