Thoughts for programmers that came to mind as I waded through cryptic output and documentation all afternoon:
- At least four semesters of writing classes, preferably technical, should be mandatory to get a Computer Science degree.
- Someone in the open source movement needs to publish a style guide. Failure to use and follow the style guide should be public shaming and shaving.
- If your output is so cryptic that I have to write PERL scripts to be able to read it at all, your software is about worthless.
- Related elements should not be in three separate areas of your output. There’s a reason surgeons like to line things up in the order they will be using them, and the same goes for computer people.
- “I gave up on calculating really small numbers, so I just rounded down to 0” is a cop-out. Some of us are extremely interested in the really small numbers
- A screen of text that amounts to “Hey, I wrote this, and this is crazy, but here’s a link to my webpage, so read that maybe” is not what I want to see when I input “man opensourceegotrip”. Yes, “man” has a manpage.
- Snarky emails in reply to polite questions about a confusing line in your documentation do nothing for my mood or my motivation to recommend your work to anyone.
- Days like this are why I agree that Unix SysAds are like ancient shaman. We both like to cover ourselves in scars to show how tough we are.
DaddyBear’s Den 
derfreiheit
/ September 6, 2012Dude its open-source. If you don’t like the man page you’re supposed to find the source code, deal with snarky comments on the dev list when you ask how to get it to compile, find out it was statically linked to some obscure version of a more obscure library, figure out the magic hardcoded paths, then make your own changes and give back to the community. Sheesh. 😛
LikeLike
daddybear71
/ September 6, 2012Yeah, that was pretty much the answer I got. Don’t like it? Rewrite it!
LikeLike
Ruth
/ September 6, 2012I took a programming class a while back, trying to keep the C++ skills up to date, I was horrified by my classmates lack of documentation, never mind lack of style….and the instructor wasn’t correcting it! I had myself a little mini rant one day, and ended with the line that any program that they wanted me to help trouble shoot (which was allowed in the class, I was one of the few experienced people in the class) had better be documented and in proper style or I wouldn’t touch it from here on out. I saw a lot of properly styled code after that….
LikeLike
derfreiheit
/ September 7, 2012Have you tried Stackoverflow.com or Unix.stackexchange.com ? They’ve been very good resources.
LikeLike
Auntie J
/ September 8, 2012I’m a copy editor by trade these days, and I’ve spent the last week doing an OMG-we’re-so-far-beyond-deadline-that-we-should-get-these-done-but-let’s-still-do-it-right panic, getting six articles edited and properly templated and all sorts of stuff, and having to divert to the OWL website on more than one occasion to make sure I’m remembering my APA formatting guidelines correctly. This particular project is the fifth I’ve done for a particular university, prior to publication of their scholarly journals online.
Most of the authors, when I find an error that I need their input to correct, are aghast and apologetic, and stumble all over themselves to let me know how sorry they are that they made a mistake. (I’m paid to catch those. I don’t mind. Honest.) And they’re respectful and thankful while they almost grovel.
Had one author this week that broke that mold. He’s a doctoral student for the university, and he had several extraneous references in his list, as well as no reference documentation for an in-text citation. So I emailed him about it. His response was to keep the references I’d asked about (weird, but ooookay), and he explained his lack of documentation for his in-text citation as “I just got it off their website.”
Based on his picture that shows up in my work email, he’s probably younger than me.
Even I know, as far removed from formal schooling as I am, that you’ve got to cite your web sources, too. Somebody who’s an active doctoral student should know that.
It was a *headdesk* moment.
It took me less than ten minutes to find the information so that I could properly list it in the references.
I wasn’t exactly in a good mood after that one, especially since I was stuck trying to figure out how to fix graphics (so not my thing) with a misspelled key word on them.
LikeLike