Documentation is where we spend a large portion of our time as programmers. If you aren’t spending large portions of time in documentation, then maybe the documentation for your tools are bad. Or maybe you’ve mastered your tools. Why not learn new tools? Perhaps ones with great documentation! Great documentation teaches you new paradigms of thinking. Great documentation inspires you to build things. Great documentation is official, interactive, and open-source.
The people who make a tool should officially endorse great documentation. Or even better, they should work closely with the documentation writers. Or best case scenario, the people who make the tool also write documentation! Good documentation should show exactly how a tool was made to be used. The official webpage of the tool should spark curiosity. The official webpage should make it easy to start learning.
Tools should have interactive examples. At the very least, there should be code snippets. Better would be running examples with the code snippets next to them. The best is when you can edit those examples and changes happen instantly! These examples should serve as great references for common things people would build using this tool. They should teach good practices through example.
Good documentation should be open source. Experts should be able to make corrections. Beginners should be able to say when things are unintuitive. Everyone should be invited to make improvements. And whenever possible, the documentation should be built with the tool it is documenting!
The following is an eclectic list of tools that I think have great documentation (in no particular order).
- The Web (Well ok… it’s MDN. Can we just call MDN the official docs of the web?)
I hope these pages inspire you to learn something interesting or build something cool!