Comprehensive Documentation

comprehensive_documentation.md

Software is layered.

Documentation is not. If your documentation states

Run npm install foo to install this module

It is really saying

• Learn how to use Terminal
• Install XCode tools
• Install homebrew
• Install node
• Learn npm
• npm install foo
• Install Sublime Text or some editor
• Learn how to use that editor
• Learn JavaScript
• Learn how to use foo in a library using npm
• Learn how foo works

This the curse of knowledge and a boatload of implicit requirements.

With computers, you cannot learn anything in isolation.

This means that a lot of tools that are accessible to programmers, like Jekyll or anything that requires a CLI, are inaccessible to everyone else.

Despite being generally a documentation maximalist - I believe that it's good to spend more time on documentation than code - I don't think that the answer is for every software project to document every step required to use it. That's unreasonable, and the task of writing documentation is hard. When you write documentation, you should have your heart in it, your spellcheck on, and be prepared to spend much more time editing than typing, and after that, maintaining. It's not something that should be done to tick a box.

---

So what's the answer? Well, a random guess would be:

Take the list of documentation needed for npm install foo, which would probably be 20k words total, and split it into things that are actually specific to foo

• npm install foo
• Learn how foo works

And those that aren't.

• Learn how to use Terminal
• Install XCode tools
• Install homebrew
• Install node
• Learn npm
• Install Sublime Text or some editor
• Learn how to use that editor
• Learn JavaScript
• Learn how to use foo in a library using npm

And then take each kind of typical install instruction:

• Install some homebrew cli utility
• Install some python module
• Install some ruby gem
• Install some server application written in node

And automatically expand modular documentation into a pipeline of tasks:

type	requirements
python module	terminal + homebrew + xcode + editor + python
node module	terminal + homebrew + xcode + editor + npm
ruby gem	terminal + homebrew + xcode + editor + rbenv + gems

It gets harder, of course: after you're done with this very OSX-centric guide, you would write swap-out parts for Windows & Linux and hope that they don't trickle down the stream for every other step.

And it gets worse the further away someone is from "a scratch install of everything": how do you install jekyll with system ruby, or rbenv, or rvm, or jruby, or in a vm, or within a build system.

---

Anyway, this is how I feel about comprehensive documentation.

I'd also add that now that's it's easier to write and publish small modules, I've found lists like these to be incredibly useful. Competency in one realm of programming doesn't mean that you're comfortable elsewhere, and seeing what others are using to solve problems you're new to makes it a hell of a lot easier to get started.