For Developers: Self Documenting Your Work
Some developers out there seem to have this incredible ability to remember the intricacies of the languages they write in and the gotchas of every obscure package they've ever used. I am most certainly not one of them. It's almost embarrassing how many times I'll google a simple implementation algorithm and read the same stack overflow post for the 19th time to remember how to do it.
Part of it is mental laziness I'm sure (far easier to google an algo when you already kind of know what you're looking for vs. trying to remember it completely) and part of it is just how my brain works.
Since I'm definitely not the only developer that has this experience, I thought I'd share my latest process for documenting my work in order to reference it later and cut development time significantly.
Enter Gists:
Gists have become my new favorite thing to implement. For the unaware gists are mini repos on github that you can just edit code in directly (without initing a repo, committing and pushing).
Really simple concept, but an insanely easy way to throw up snippets of useful code (and find useful code even by searching) to a place online that's easily searchable. You can make them private (if proprietary) or share the love and publish your most useful bits for the world to see.
Another great thing I noticed is that if you post on wordpress, gists are a great way to handle embedding code snippets for technical articles and documentation posts. Simply install the oEmbed Gist plugin, publish your gist, and paste the public link into any post. The plugin will convert it into a syntax perfect embed automatically.
Here's an example of a gist embedded.
https://gist.github.com/ethandrower/e272976ae5c090d59451e6cf54578e95
Conclusion
While I am always dedicated to documenting full products I build and personal repositories, I've been notoriously bad at documenting code/algorithms for my own personal use in future projects. I'm hoping that with this simple process I can start wracking up a library of my most useful functions that will pay dividends down the line.
Happy gisting!