Documentation is key. so where the hell is yours?

I’ve been known to get my hands dirty with this or that random project. Occasionally, resulting in the consumption of something a bit stronger than the coke I often keep nearby. Sometimes, I do it pretty much by the seat of my pants–this looks like it goes over here, so let’s see what this does. And sometimes, either by choice or by force, I’ll actually have to go hunting for documentation. Occasionally, the hunt points me to the developer’s website, the developer’s twitter, the developer’s blog–but not, in fact, the developer’s documentation. Or any documentation, for that matter. A user manual? A half-page thing on someone’s personal, but publicly accessible, WIKI? Yeah, no.

admitedly, I occasionally have that very same problem with my twitter app of choice, but in this case there’s documentation, it’s just not in English. So it *could*, if it was absolutely needed, be translated. Awesome. Useful. I should get on that, eventually. But in cases where there’s no documentation, as in whatsoever, for this or that program, script, basic language or other such extra utility, it has to be asked–and Slashdot asks it–what the hell are you thinking?

You want your program, script, language, basic little utility to be used, yeah? And not solely by geeks with little else to do between job searches and family things but to try busting things, yeah? Yeah. thought as much. So, uh, how about manualing the hell out of it? Nothing says “oh crap” more than smacking the help option and being directed to a website that tosses me a 404 error instead of something useful, like a FAQ. And, if I don’t feel like playing a guessing game–usually because I’ve got 80 million other things to do as it is–nothing convinces me to toss your program in the maybe later pile faster. And probably increases the likelyhood of me forgetting I have that program, simply by virtue of its presence in the maybe later pile. I’m not averse to doing a little RTFM every now and again. Hell, maybe I’ll catch something obvious that gives me an excuse to redo something and easily waste away an evening I can’t spend watching hockey. But by all means, couldja maybe pretty please try and WTFM–write the fucking manual? It helps, I promise. Or, at least, it makes you immune to entries like this one. Which is always good.

Post a comment

You may use the following HTML:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>
http://www.the-jdh.com/2012/12/documentation-is-key-so-where-the-hell-is-yours/
www.the-jdh.com
crawl=CC-MAIN-2016-30
55881
application/http; msgtype=response
sha1:OEL2NKNDZC42GR5SNQ7HJ6IIUYG6GGD6
<urn:uuid:b7c4efd7-0ddb-465f-97c8-7c047e79a691>
2016-07-26T15:57:21Z
75.126.137.86
sha1:DKNRZMWJ7AYYVDFPQRRCBD366PN2F5VQ
<urn:uuid:136a2f61-ce1d-4359-95ad-88dc6d65de95>
http://www.the-jdh.com/2012/12/documentation-is-key-so-where-the-hell-is-yours/
length
response
<urn:uuid:bd90a0e4-70f2-49f4-905d-893e6b52bff4>
robots: classic
hostname: ip-10-185-27-174.ec2.internal
software: Nutch 1.6 (CC)/CC WarcExport 1.0
isPartOf: CC-MAIN-2016-30
operator: CommonCrawl Admin
description: Wide crawl of the web for July 2016
publisher: CommonCrawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf