When API Documentation Is So Bad that It’s Good, Part 2

Response Codes and Errors

The following list presents our potential error codes:

Error Code Error Message Description
7734 Something Definitely Happened …but we’re not exactly sure what.
1334637 Not This Time It failed? Try again. Did it work? Okay, good. What happened? You’ll never know.
3704558 Success with Errors Meaning that we did what you wanted…but then something bad happened, also. Like the database was erased. Or something.
450087734 No Just…no, man. No way. No.
580083351 Invalid Parameter Some of your data was bad…What? You want us to tell you which parameter had the bad data? I’m not your damn slave. You figure it out, you pushy asshole.
580087734 Deprecated Method This method doesn’t work anymore because we’ve disabled it. We could have forwarded your request to its replacement, in order to be backward compatible…but we didn’t. Why? Because we hate you.
5800808537 Multidimensional Error So, basically, take this error code and pass it (along with your UserID) to the GetSpecialErrorCd method. Now, take the result of that method call and multiply it by your UserID to get the resulting product…which is how much you’re gonna need to pay us in order to help you figure this one out.

Peter Bolton is the author of Blowing the Bridge: A Software Story and has also been known to be a grumpy bastard on occasion.

Advertisements

All Your Character Encoding Belong to Us, Western Europe

Listen, Western Europe…North America has a great deal to thank you for. You are, of course, our big brother…and we’re really glad that you led the way. However, we’re a little ahead of you on certain things, and we need to get something straight: older doesn’t necessarily mean better. And when it comes to character sets for languages, you’re really starting to show your age. Much like the show Hoarders, I know that you have a hard time letting go of your “treasures”…but, really, it’s for the best. Now, I’m not suggesting that certain garbage characters be dropped entirely; I’m sure that your ministers of culture are already seething at the mere mention of it. Of course, you can use them without reservation in your daily lives for useless fun. (Like calligraphy!) For the sake of computing, however, it’d be better for all software developers (and everyone in general) if you just converted all electronic text to ASCII…and I’m willing to bet some of my Western Europe counterparts would agree with me.

Imagine a world where we wouldn’t have to ask “Is this character in encoding Windows-1252 but not in encoding ISO-8859-1?” That place could be real! Just think about that for a moment…it would be beautiful, wouldn’t it? Together, we can make that happen. So, let’s take that initial step of purging your electronic banks of filthy, superfluous text. Much like Hoarders, we need to step through each “treasure” and mull over its inherent worthlessness…I mean, “value”…to your respective languages:

Ligatures – Come on…we both know that they’re stupid. Æ and Œ were created by drunk Trappist monks, when they were sloppily copying books with cramped hands. Afterwards, when someone pointed out their mistakes, they said “Uh, no, I meant to do that. Those are real letters.” And thus ligatures were born. Even more and more of your populations have stopped using it, and they split them into “AE” and “OE”. You know that it’s dying. Drop them.

Umlauts – We’re not even going to address diacritics for now and how everyone should just use normal tittles. I said tittles! Stop laughing! In any case, we’ll address that diacritic bullshit some other day…First, I have most encodings on my side: they don’t distinguish between umlauts and diaeresi. (Even Unicode is like “I don’t give a shit.”) Second, each country has its own version of them! You formed the EU for a reason…start standardizing that shit! Three, I understand the purpose of umlauts: to help a nascent reader with the pronouncing of vowels that are next to each other…but in North America, we eventually get it after some direction and practice. We don’t need diagrams and pie charts in order to learn how to pronounce “cooperate” properly. Trust me…you can, too.

Cedilla – Even though I’m against diaeresi, I understand that they’re useful, especially to novice readers. But a cedilla? You can’t just replace “ç” with a “sc”, “ts”, or even a “z”? Because it’s so special, of course. Did an ancient Spanish or French monarch allow their child to doodle while writing…and then it was decreed that the doodle was official henceforth? (Personally, since I love the movie Aliens, I’ve always liked to doodle little snapping jaws shooting out of everything. If it hadn’t been invented in the Middle Ages, I probably would have invented the cedilla…but if would have looked different.) It doesn’t matter. We all know how useless monarchs are…that, and how they generally look better without heads. (That’s a tip of the hat to you, Frenchies.) In any case, like monarchs, the cedilla is a complete waste. Into the trashcan.

You see how easy that was, my brethren in Western Europe? We got rid of three different types of characters…in one shot! That’s at least dozens (if not hundreds) of characters that we can free from our collective banks of data! By using just ASCII, we can use half of the data needed, which means almost half of the processing power. Think about how many baby seals that could save…and you don’t to kill baby seals, do you? I’m sure that John Lennon would have written an extra verse about this very subject in “Imagine”, if he had just lived long enough. It might take some time, but eventually, we can live free of an Encoding Hell. Leave Unicode to the rest of the world and its craziness…and join hands with us, so we can finally blow that bridge together. ASCII and freedom for all! You just have to believe, Western Europe. Just believe.

10 Episode Ideas for Mike Judge’s Silicon Valley

1.) Erlich Challenges James Gosling and Richard Stallman to a Beard-Off

2.) Gilfoyle & Dinesh Go to In-N-Out Burger (and Party “Animal Style”)

3.) The NSA’s Ultimatum to Richard: A Backdoor to His Compression Algorithm…or His Backdoor

4.) Dinesh Becomes a Hooli Spy by Impersonating Deepak Chopra and Mentoring Gavin

5.) Big Head and Mochachino Collaborate on a New App Called “Chubber” (Which Finds a Strip Club that Matches Your Perfect Stripper Measurements)

6.) Jared Meets with an Outsourcing Firm in the Ukraine, Gets Mistakenly Kidnapped by Russians, and Ends Up Naked in a Banja with Snowden

7.) The Dark Lord Tells Gilfoyle that He Must Kill Brian Krebs, but It Turns Out that Brian Krebs Is the Dark Lord

8.) Peter Gregory Forms ’DropoutsCannot-Code.Org’ Just to Spite His Nemesis Mark Zuckerberg

9.) Erlich Meets His Good Friend John McAfee in Oregon, where They Get Chased by Criminals while Seeking Pirate Treasure

10.) Monica Introduces Richard to Jeff Bezos, Who Will Invest in Pied Piper if Richard Can Beat Him in a Shirts Vs. Skins Segway Streetball Game

Peter Bolton is the author of Blowing the Bridge: A Software Story and has also been known to be a grumpy bastard on occasion.

10 Tips for a Software Résumé



1.) If you list “Software Engineer” as a job title, there should be examples of actual engineering listed somewhere. “Got Visual Basic working with Excel spreadsheet” does not count as software engineering…nor does that really count as programming. It’s a thin argument to even place that in the category of “software”.

2.) If you’ve worked at 7 different jobs over the past week alone, you might want to manipulate your résumé so it isn’t immediately apparent that you’ll cut out at a moment’s notice.

3.) In your list of technologies with which you are familiar, please refrain from mentioning tools which have lived long past their use or relevance. Nobody is going to be impressed that you used Windows 3.11. You might as well mention that you played a Sega Dreamcast at one point and that you’re fairly sure one of your ancient ancestors used a wheel before it became popular.

4.) If you’ve worked in the technical field for more than ten years and if you graduated much longer ago than even that, there really isn’t a need to mention the school. Plus, if you graduated in Asia and are working in the U.S., it’s completely ignored. (In the case of IT, most IT managers won’t even know the school that you’re referring to, let alone tie their shoelaces by themselves.) You could put down that you have a Master CPU degree from Kali Ma Shakti De University in Pankot, with a minor in archaeology…and nobody will be the wiser.

5.) If you want to highlight your strengths (such as your ability to work with teams and your keen meticulousness), you should present yourself in such a way as to demonstrate them. Writing “Excellent communikation skills and very talented at talking” actually works against you.

6.) By default, all of those who don the hat of a technical screener (like myself) assume that every candidate is going to naturally present himself/herself in the most positive of light. Having said that, if I see another résumé with the phrase “great team player”, I’m going to actually play baseball with a candidate’s head by introducing it to a Louisville Slugger.

7.) Since you’re supposedly a qualified worker in the technology field, your résumé should naturally be prepared with a certain amount of technical finesse. When your document is presented with an heterogeneous mix of Arial, Times New Roman, and Verdana, it doesn’t inspire confidence in potential employers when you can’t even slay the dreaded monster of Font.

8.) Please refrain from boring the living shit of the person reading your C.V. by filling it with nonsense. Since I assume that you have used a keyboard at one point as a peripheral device and that you went to a meeting where you talked to people (in order to “brainstorm”), you do not have to write those activities down. I also assume that you didn’t defecate in your pants one afternoon, using your new cargo to write your name on the lunchroom wall…but you don’t need to write that down. (To be fair, though, I would enjoy reading that if I stumbled upon it.)

9.) For software developers and engineers, one way of showing your proficiency with abstractions is to demonstrate the summarization of data. So, when you list 20 specific projects that have an overwhelming overlap in functionality, you’ve shown me that on top of not being proficient, you are likely mentally disabled. I don’t care if you have “created a back-end that supports the front-end” twenty times in different scenarios. If you list it more than once, you’re an idiot.

10.) If you claim to be a writer of technical documentation but you’ve only used three verbs throughout your entire résumé (and I’m betting that those words are ‘developed’, ‘designed’, and ‘analyzed’), then you probably have a better chance of impressing me with illustrations drawn in pen and crayon. Remove that part about writing good technical documentation, and we’ll accept your possible employment with the footnote that you’re an illiterate simpleton.

Peter Bolton is the author of Blowing the Bridge: A Software Story and has also been known to be a grumpy bastard on occasion.

When API Documentation Is So Bad that It’s Good



Web Method
data.postData

Description
Post some data to another piece of data (i.e., “data data”), which will be related to some other data. You know…the other data. You’re not confused with all this ambiguity, are you?
Notes: In order to be less confusing, we will now refer to the other data as “Smegma Lite”. If you are posting data related to Smegma Lite, please notice that there are other related parameters which are not mentioned here. Learn more in the “Smegma Lite: Why Do I Need to Read a Fucking Manual About This Mundane Concept” guide.

Request URL
http[s]://ima.weiner.com/carlosdanger/data.postData

Parameters

Required Level Name Type Description
Required DataType string The type of the data. (Honestly, if you actually needed that, you’re better off sticking a handgun up your ass and pulling the trigger.)
Required Data string You need this, too? And you survived after my last instruction? Okay, now put the gun to your head.
Mostly Required DataId string It identifies the data. On a side note, if it’s empty, the default value is assumed to blank. What does that mean? Who the hell knows. Maybe it wipes out the entire database. Do I look like I care? I’m writing these docs while I’m huffing paint.
Sometimes Required SubmitterID Int It may or may not be required…I’ll get back to you later on that. If it’s not specified, the default value is 590091134. (Upside down, that does not spell “Hell Boobs”, it spells “He’ll Boo BS”. You’re so immature. I just don’t get you anymore.)
Optional guestName string If the submitter is a guest user, then this field is Required…which means it isn’t Optional…hmmm…
Quasi-Optional guestAlias string But if the submitter is a guest user and the guest name is only one word, then this field is Required and the guestName field should be omitted…which means it isn’t Optional and it isn’t Required.
Superposition-Optional guestNameAlias string If the submitter is a guest user and the guest name is both one word and more than one word at the same time, use this field. This isn’t confusing yet, is it? Because it’s pretty simple stuff, moron.
Required for Some Data and Not for Data that Isn’t Some Data dataSynopsis string If your user account allows a synopsis for data and if your data is related to Smegma Lite and if your guestName comes to a Scrabble score of 50 and if you blew the bridge on Wednesday, then you are allowed to post graphic pornography to your account. As for the ‘dataSynopsis’ parameter, you can always use it. That’s a given. Duh.

—–

…and if you think that any documentation resembling this format passes as adequate, you should be deemed a pariah and removed from society by being banished to the new edition of the show Naked and Afraid, which will take place in a nearby asteroid belt.

Peter Bolton is the author of Blowing the Bridge: A Software Story and has also been known to be a grumpy bastard on occasion.