Tuesday 24 November 2015

RTFM, WABM & the "Spirit of the Internet" - why this blog exists.

I've now more or less built a career out of "standing on the shoulders of giants". There are countless nameless individuals out there who have given selflessly of their time and expertise to create great software for us to use, or providing helpful guides, or helpful comments in forums and the like (somewhat ironically, RTFM is not a helpful comment). There are also in person mentors I've learnt a lot from by watching them work, or listening to the advice and insights they offer (if not outright interrogating them about things I want to know more about!). The entire Internet is more or less built out of "gentlemen's agreements" (or at least, much of it used to be built that way). I don't think I'm alone in feeling that making use of that rich treasure-trove of knowledge incurs a moral debt to "give back" as much as you are able.

This blog attempts to do several things, including: being a somewhat applied creative writing outlet (in previous jobs, I did a lot of writing; I kind of miss it); documenting things in case I need to redo them or wonder how the hell I did that thing 5 years ago (although I have also set up and extensively use an in-house MediaWiki for internal documentation); last, but not least, "giving back" to the community at large. I have learnt countless things over the years simply by reading about them on the Internet, and of course by "hacking" (in the old "Unix hippie" sense) away at things. Somebody put them there. This is my small contribution to repay/service that kind of "debt".


You'll often hear techies suggesting you ought to RTFM (or JFGI). Sometimes, the manual doesn't help - or doesn't exist, or doesn't quite work in your environment. In such cases, you should figure it out anyway, and once you do, WABM (Write A Better Manual) - and contribute it back, particularly if it's likely to be useful to others. Often, there isn't a single manual - you cobble things together out of many disparate threads to make a cohesive whole. You can save a heck of a lot of time by following a guide that does things step-by-step to provide/build exactly what you need. You can also work it out by googling things (often for days) - documentation of what you did in the end not only serves as a "recipe" for the next time you have to do it, it also helps to cement the knowledge in your mind, and sharing it will probably save someone else some time down the line - often your co-workers if you're fortunate enough to have co-workers.

The only thing better for building and retaining knowledge than doing-it-yourself and documenting a solution (or contributing code or script if you have talents in those areas) is teaching it to others. Even if you're not a member of teaching staff, start a computer club that teaches interested kids what you think is important - focusing on practical things they can play with which they'll find useful day-to-day or as they go off to pursue careers of their own - whether IT related or not. In particular, if you're lucky enough to work in a team, take time to coach, mentor and train any fellow staff members, particularly junior ones (and in turn, never be closed off from the idea that others have plenty to teach you). Yes, you risk one day "loosing" them to a better paid position, but I think there is deep wisdom in the concept of the "cost" of NOT training people!

Topics will obviously be biased by what technologies I play with or have access to. I might like to write a manual for an arcane, expensive piece of gear, but if I can't play with it, I can't write about it! For the most part, by applying some "lateral thinking" you can often adapt a technical guide to a slightly different set of tools.

Hopefully, others will find useful guides or insights in these virtual pages!

Do leave comments if you wish to; it's always nice to know you're not simply "howling into the void"! I'll address those I can, as and when I'm able in amongst my duties, or when I notice comments have been added.
http://blog.klocwork.com/user-documentation/if-you-want-users-to-rtfm-write-a-better-fm/

No comments:

Post a Comment