Handbooks & Cheat Sheets

Lately, I've been toying around a lot with the idea of making and using my own handbooks. Usually, what an experienced dev needs to be effective is exactly what a handbook provides: A list of the idiomatic concerns which need to be addressed and the glue code needed to match those idioms to existing abstractions effeciently. Of course, there's always other work that needs to happen; problems that actually need solving that aren’t trivial or totally idiomatic. But those processes and problems are nuanced and those are the things we want to invest time into. What we don't want is to invest a huge chunk of time recreating so many idioms which already have solutions.

In light of that, I think a good handbook should include:

  • Links to relevant guides / tuts.
  • References to relevant API reference docs
  • Example code that addresses non-trivial use cases
  • A concise overview of the concerns involved, especially when those concerns aren't obvious from the code itself. Concerns directly addressed by the example code should generally just be explained in the comments. Consider using diagrams here, if it's appropriate.
  • An overview of the gotchas: Stuff that's easy to get wrong or that we've gotten wrong before.

Cheat Sheets as Handbooks

Often, a cheat sheet can be a very good handbook. Whether you need more than a cheat sheet just depends on whether the other aspects that need to be addressed are obvious or not. For instance, creating a link to the man pages for ssh probably isn't necessary and the code that results from using the options is probably pretty self-explanatory. Use your judgement.

Conclusion

The most important thing here is that the handbook "feels" like something you can reference easily and quickly and it should get you through common problems that don’t want to and shouldn’t want to resolve. Make sure that you know where to find it and keep it curated.