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

Web Method

Apparently, for some of you out there, it was not simply enough that you could just save data as a record with a provided ID. No…that wasn’t enough. Some of you bastards have insisted on moving data from one record to another. Who would need to do such a thing?!? Personally, you make me sick…but since you’re our special client, we have implemented the precious functionality that you need from us.

Request URL


Required Level Name Type Description
Required SourceID String The ID of the record from which data is being moved.
Required TargetID String The ID of the record to which data is being moved.

And there you go…happy, assholes? Oh, but I forgot…there are a few more additional steps after you call the method…

1.) The return value of this method is a string (which we will refer to as your TrouserKey); you will want to hold onto this for future use.

2.) Since the method is asynchronous, you will need to wait an undetermined amount of time before the data is actually moved. Usually, depending on the weather, this interregnum is somewhere between several minutes and a couple of days. However, you are allowed to occasionally (occasionally!) call our “hasBeenMoved” method, using your TrouserKey to see if the data has been moved yet.

3.) After repeatedly poking us with your TrouserKey and finally getting a Success from the “hasBeenMoved” method, you should get ready to call the “getMovedStatus” method. Since your data is important to us, we do provide two-factor authentication when getting the status of your data. So, at this point, we will wardial your company’s location and send you a fax with a PIN number. (Not to worry…if you don’t own a fax machine, we will send you a FedEx package with the PIN number in it.)

4.) Finally, after receiving your PIN number, you can use your TrouserKey and PIN number to call the “getMovedStatus” method, and then…voilà! We will return a formatted URL with embedded JSON in it…which, when you think about it as a smart person, makes sense. It will look something like this:


I don’t often say this…but that’s just beautiful, plain and simple. And it totally makes sense to do it that way. Totally.

5.) After calling the URL, we will return a simple text page that will have either a “Success” or “Failure” in big, bold letters. If you wish to know the reason for the failure, you’ll need to call our support number and be ready to communicate in Swahili.

It’s that easy! And if you don’t like it…? Go suck it! I ain’t breakin’ my back for you, asshat.

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

What a Developer Says Vs. What a Manager Hears

Developer Says: Based on our design, I could have a MVP done in a week. Afterwards, we can go over that, pivot the design, and then build a more substantial iteration by the end of the following week.
Manager Hears: The whole thing will be done in two weeks.

Developer Says: Yeah, with my limited knowledge and a few of my favorite tools, I can build some web services that can allow fellow company programmers to interact with our system.
Manager Hears: By myself, I can construct a load-balanced Web site that will accommodate millions of global users per minute.

Developer Says: We should have a meeting with release engineering and stress that we can’t meet deadlines without proper build and deployment machines.
Manager Hears: Waaaaaaah…[cry tear, emit snot bubble from nose, kick legs while in diaper] Waaaaaaahhhh…

Developer Says: We need to establish ownership of our various software projects, so that people can be held accountable.
Manager Hears: I am willing to take full ownership of all software projects, and I volunteer to be the official company scapegoat.

Developer Says: When you write a web method with HTTP GET, it should generally only return data. With a web method that writes data, it should really use either POST or PUT.
Manager Hears: Blah, blah, blah…I’m a flaming, anal-retentive nerd who has to have everything in a certain way, because getting things right is as important as my Tolkien underwear….blah, blah, blah…

Developer Says: Dinesh and Gilfoyle have reverse-engineered some of the legacy programs, and they’ve found inconsistencies with some of your old specs.
Manager Hears: We should fire Dinesh and Gilfoyle.

Developer Says: Since we’re in a crunch period, I guess that I can remote onto my dev machine from home this weekend, in order to get some work done and to get us a little ahead of the curve.
Manager Hears: I will gladly blow the bridge and die smiling in an attempt to save this impossible project…and even if my near-future reincarnation is about to be aborted in a clinic, my bloody fetus of a body will jump out and crawl back here, so that I can once more be a martyr for your noble cause. Please use me as you see fit.

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, 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.

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.

The Pros and Cons of Agile Methods


1.) Pair Programming

Pros – It encourages better practices of development, decreases bug occurrence, and ensures redundancy in working knowledge of software.
Cons – It either gets in the way of your personal downtime activities, like searching for nude pics of Alexandra Daddario…or it leads to an oddly intimate relationship between you and your PP partner.

2.) Use Cases

Pros – It propels developers and stakeholders to predict and plan for various scenarios of your software’s usage.
Cons – It empowers morons to participate in the process. “So, what if a feminist Eskimo were insulted by the phallic nature of the igloo in your button’s image? And if a luddite or Amish person wanted to use the software, could we make the computer run on the churning of butter?”

3.) Scrum Meetings

Pros – Developers and their boss avoid any surprising obstacles or misses of expectations by having regular daily discussions about their current progress.
Cons – Since some people don’t relate the word “scrum” with “brief”, an expected fifteen-minute conversation becomes an hour-long dissertation from Bob about how the Illuminati are running the company and about how he blew the bridge last year. Every. Single. Day.

4.) Cross-Functional Teams

Pros – Developers with different areas of expertise work alongside in order to better understand the issues faced by different departments and in order to create more innovative solutions.
Cons – Sometimes, the “powers-that-be” don’t seem to understand how to properly form a cross-functional team. “Why am I in the same room as the maintenance guy and the building’s bomb-sniffing dog?”

5.) Planning Poker

Pros– During a Scrum session, the usage of cards (instead of vocal answers) will create a more accurate estimation of time required for tasks, since the vocal answers of one could influence others’ estimates.
Cons – Its implementation increases the chance of a violent gambling ring among your software developers, which then naturally leads to the formation of mob families in your department. Productivity will naturally decrease when your developers start missing fingers.

6.) Timeboxing

Pros – By creating a physical visual chart that tracks your project’s progress instead of a hard timeline, you can get a more accurate picture of the current status and impending direction of your work.
Cons – Sometimes timeboxes can become a bit ‘crowded’. “Can we knock out this wall here? I’m going to need a bit more room…I also need somewhere to put this pallet of sticky notes…”

7.) Story-Driven Modeling

Pros – Developers and users get together in order to create detailed usage scenarios for the software, which then reveals new requirements and possible issues when further developing and/or enhancing the software.
Cons – Sometimes pairing certain developers and users can be counter-productive, especially if they develop and chronicle a relationship outside of work. “So, Peter orders a box of condoms by clicking on the ‘Purchase’ button, and then Mary hits the ‘Agree’ button in order to book the hotel room, and then [Insert Explicit Actions Here], followed by [Insert Explicit Image Here].”

8.) Test-Driven Development

Pros – By requiring developers to create tests for their functions before they implement them fully, it helps to ensure that the results are kept in the forefront of the developers’ minds.
Cons – For your more ‘special’ developers, this development style could then be mistakenly combined with their recursive practices, resulting in an infinite spiral where a testing harness is created for unit tests that gauge results from another testing harness…until they piss off the system, are absorbed into the circuitry, and must fight alongside an even older Jeff Bridges against the Uber APU in order to save humanity.

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 Lessons from 10 Years in Corporate IT

1.)  Never concede that an employee’s value to the company deserves a hefty increase in salary (as in 25% or higher).  Instead, it is better to wait for the employee to quit, suffer from their absence for months or perhaps years, and then hire them back at twice their original salary (plus six months of vacation).

2.) An annual review is an opportunity to showcase one’s contributions for various software projects during the past year, with the hopes that it will merit a reward. However, since management never records actionable metrics, all claims are treated as hearsay, and you have as much of a chance for a fair trial as a young girl accused of witchcraft in 17th century Salem (or 20th century Arkansas).

3.)  Management will hire vendors and consultants based on:
     a.) honesty and accuracy when it comes to performance metrics and project status.
     b.) proficiency in knowledge of utilized platforms and efficiency in implementations.
     c.) the level of blame and bullshit that they will swallow without choking to death.

4.) The more distant from Computer Science was your college major, the more eligible that you will be as the manager of a software project.  If you majored in gym, you’re a slam dunk.

5.)  If you don’t engage in code reviews with the antisocial programmer of your group, you’re taking a significant risk.  In the best case, he will develop code without being encumbered, and he will beat project deadlines.  In the worst case, he will start to lose his connection with humanity like Colonel Kurtz from Apocalypse Now, and after convincing the maintenance staff of being a deity, he will plot to murder the entire floor from his bamboo-covered cubicle.

6.)  Tolerance is an incredibly important aspect when managing personnel in an IT department.  If a programmer or admin says that their faith precludes them from command-line prompts and that their culture forbids the use of keyboards, you should learn to encourage acceptance within the group and leave them alone…especially since firing pernicious people can lead to punishing litigation.  Instead, it is better to passively wait for a round of layoffs, throw them into the grinder when nobody is looking, and then feign sorrowful surprise to your subordinates at your next Scrum meeting.

7.)  When you first start in IT, you will read and then curse the source from all legacy programs and system scripts.  In order to ameliorate the pain, you will begin to drink at work, and as the years pass, you will develop code through the reddish hue of seething anger and alcoholic stupor.  When you quit or perish from the bamboo spear of a nearby antisocial programmer, a nascent employee will inherit your insane gibberish, and then the cycle will begin anew.

8.)  Typically, as a manager, your assignment of allocated time for a project should be:
    a.)  2% on R&D
    b.)  2% on the original design
    c.)  25% in political strutting and squawking
    d.)  25% in throwing out the original design and debating with upper management about whether the project should exist
    e.)  20% in arguing over the scope of manpower and the cost of the budget
    f.)   15% in replacing those developers and admins who left in disgust
    g.)  10% in impromptu cage fights with HR managers
    h.)  1% on final implementation

9.) When your boss says “I need to understand this from a bird’s point of view”, it is important to take him literally.  You should skip the technical complexity of your explanation, feed him bird seeds, and then paint a bullseye on the whiteboard for him to aim and defecate upon.

10.)  In order to truly learn about the best practices and technology available, it is important to remember that failure is always an option…as long as you’re not the one doing the failing.  When someone does fail, though, it is important that you point and laugh at them. Don’t laugh too hard, though. In defeat, there is still honor in blowing the bridge.

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