Tag Archives: programming

Optimization

Posted on by
Reply

Tonight it hit me, as I was giving advice, that I was dispensing wisdom I would do well to listen to myself. It was a question about optimization. Whenever you use that word, you have to know what you are optimizing for. Sometimes I forget.

One of the approximations of social media I engage in is a place called StackOverflow.com. That site and dozens of its sisters are an indispensable resource for programmers and tech folk in general. Some nights, like tonight, when I’m a little adrift, I will stop by over there and see if there are any questions pending I am qualified to answer.

When you’ve been around a while, you realize that there are almost no new questions, and in the major categories there are semi-pro question-answerers who can swiftly point the new question to the ancient answer. For php, you will see the name Barmar time and again, always helpful, always gentle.

But there is a category of question that in general is found to be annoying on Stack Overflow, but that I can answer well. These are questions that go beyond the nuts-and-bolts of a language to get to the heart of what programming really is. I will see the code they post, often a mess, and I can sort through it and figure out what is the actual question.

While others will downvote the question for being a mess, I find an opportunity to teach. I see someone who, with a little help, will see the mess also. My answers are long, and meticulous, but if I feel like I’m answering a homework question I leave out the key stones in the path.

A recent example: Someone had code that took the result of a database query and built an html table. But the result of the query didn’t directly match what was to go into the table. So while drawing the table, the code was also trying to figure shit out.

I suggested that while there was no way I was going to figure out what was wrong with the code as written, I had a simple concept to apply: Think, then Draw. Get all the information set up beforehand so that creating the html was just a brain-dead loop.

I have discovered that I have axioms. One is “Keep the guards close to the gate.” Another, apparently, is “Think, then draw.”

Tonight I came across a question asking for how to optimize a data manipulation operation. Massive data in, then a rearrangement of the data to be more useful later. The code to accomplish the data transform included nested loops, but was pretty tight and pretty clean. “How do I optimize this?” was the question.

I have come to realize that optimization of code is an economic judgement, not a technical one. The most obvious tradeoff: You can use more memory to make your process run faster.

But there is another, more subtle, economic tradeoff. Tonight I answered the optimization question with another economic argument: that Engineer Hours are worth more then CPU milliseconds. I told that person that if their code worked, and there wasn’t a specific problem caused by it, then it was perfect and they should move on to the next problem. I told that programmer to value their own time. Not just for personal reasons, but to better judge how their time could best help their endeavor.

Value your time, but also recognize the cost of your time.

My friends, this is something I do not do well. Where I work, I am moving our stuff from an environment where it was hosted for free, to a place where we will have to pay for the resources. I am, at heart, a cheap bastard. While that does me well at the poker table, it may not always serve the interests of my employer. I am constantly aware that all resources I request will now be billed.

So I spend time, hours of my time, trying to guess how small a footprint I can squeeze into on behalf of our group. I spend hours on elaborate schemes to do more with less. But I am not serving my clients well. I’m not including the cost of my time in the value equation. Things are too slow? I could spend a week doing clever stuff, at a cost to my company of thousands of dollars in my compensation while I defer projects that actually will make things run better, or I could just submit a form and get more RAM for the database, at an incremental cost for the department each month.

In my defense, I HATE filling out forms. I HATE the call that comes after while someone else re-enters the form into a different system, and invariably makes a mistake. I will take a week with the code over an afternoon of nonsense any time. But that is a weakness, not a strength. That is me allowing my own preferences to make decisions that are not properly optimized.

I am, at heart, a person who can take a problem and slice it and slice it and slice it until each part is a simple question, and I can take the answers to those questions and combine them to arrive at the solution. While I’m at it, I’ll make tests so that each part proves itself. When you see my code at the flea market, it will be on the shelf behind the table, where you will have to ask to get a closer look. I am proud of this. But it is not always a good thing.

There was a time I was VP of Software Engineering at a small company, and I did all right in that role. During the dot-com boom I held a pretty dang good team together. I didn’t have to fill out forms then, either. We were all just building something awesome. The calculus of the value of my time was different then; Engineer-hours — my hours — were a commodity; the value only to be realized if the venture succeeded. (Picture Facebook, before Facebook, only far more dynamic, with the fatal flaw of being private.)

Good times, good times. The sleep-optional days of youth. But if I’m going to justify that little walk in the past in this ramble, I have to tie it to the present.

Back then, I was paid well enough but there was never doubt that Engineer Hours were the currency we were paying to make our name. Our data center was a few racks in a room that had once been a bank vault (AWS was decades away yet). Everything, everything, was optimized for minimum CPU.

Tonight, while I was (very gracefully I’m sure) reminding a young coder about the relative value of CPU cycles relative to neuron flashes, I realized that I have not been very good at making that judgement myself. I need to do better. Not just for my team, but for myself. I need to fill out the goddam form, bluster my way to 4x the resources I actually think we need (magnificently tiny, in the scale of my company), and recognize that my time is better spent making new things, rather than helping the old things go.

4

Thanks!

php’s missing array_usearch

Posted on by
2

Pure geekery today, kids.

php has a bunch of functions that work on arrays. (In most modern languages arrays are defined by classes or prototypes and have methods built-in. php is not a modern language.) There are functions like array_sort that takes an array and puts the elements of that array in order. That’s fine if you have an array of numbers or strings, but for more complex things, how does the code decide which comes first?

For that use, there is another function, array_usort that takes an array, and you tell it what code to use to compare the two items.

php also has a method called array_search which finds whether an array has a particular item in it. As before this works fine for simple items, but becomes less useful as the items in the array grow in complexity, or you want to find something that you don’t already have a full example of. What if you have a list of books and you want to find the one titled Huckleberry Finn?

It seems logical that there would be a search function where, as for array_usort, you tell the code what defines a “match”, and then off it goes to see what comes up. Logical, but it’s not there (unless it’s tucked away with a terrible name that makes no sense, which is entirely possible in php).

So after about the eleventy-hundredth time writing a little loop to find something in an array I said, “dangit, I’m writing array_usearch.”

function array_usearch(array $array, Closure $test) {
    $found = false;
    $iterator = new ArrayIterator($array);
 
    while ($found === false && $iterator->valid()) {
        if ($test($iterator->current())) {
            $found = $iterator->key();
        }
        $iterator->next();
    }
 
    return $found;
}

All this does is try each element in the array against a function you provide until the function returns true, then it returns the key for that item in the array. If no match is found, it returns false, the same way array_search does. Simple! Using it would look something like this:

// define a type to put into a list
class Thing  {
    public $id;
    public $name;
 
    public function __construct($id, $name, $category) {
        $this->id = $id;
        $this->name = $name;
    }
}
 
// make a list of them, mixed up a bit
$listOfThings = [
    new Thing(1, 'one'),
    new Thing(2, 'two'),
    new Thing(4, 'four'),
    new Thing(3, 'three'),
];
 
// find the index of the item with id = 4
$id4Index = array_usearch($listOfThings, function($thing) {
    return $thing->id === 4;
});
// $id4Index will now be 2

The function will work on all php array types, whether with numeric indices or strings.

php purists might object to using the name array_usearch because all the other array_u* functions take a callable for defining the function, while this version uses a Closure. There are a couple of reasons: 1) Closures didn’t exist in php when the array_u* functions were defined, 2) it’s the 21st century now and other languages use closures in this manner for a reason, and 3) closures allow the function that gets passed to array_usearch to be reused with different values. With a little extra setup we can make searching super-clean:

// function that returns an anonymous function that captures the id to search for
$idClosure = function($id) {
    return function($item) use ($id) {
        return $item->id = $id;
    }
}
 
$id4Index = array_usearch($idClosure(4)); // value will be 2
$id2Index = array_usearch($idClosure(2)); // value will be 1

Now we can write code compactly that can search for matches of arbitrary complexity, and we can create little factories to produce the search functions themselves, so the complexity is tucked away out of sight. This variation takes an array of key/value pairs and searches for items that match all of those values:

function firstIndexMatching(array $array, array $criteria, bool $useStrict = true) {
 
    if (count($criteria) < 1) {
        return false;
    }
 
    // create a closure that has captured the search criteria
    $testWithCriteria = function($criteria, $useStrict) {
 
        return function($item) use ($criteria, $useStrict) {
 
            foreach($criteria as $key => $value) {
                if (!isset($item->$key)) {
                    return false;
                } else if ($useStrict && $item->$key !== $value) {
                    return false;
                } else if (!$useStrict && $item->$key != $value) {
                    return false;
                }
            }
 
            return true;
        };
    };
 
    return array_usearch($array, $testWithCriteria($criteria, $useStrict));
}

Now if you have an array of people, for instance, you can search for the first match with a given name:

$joeCoolIndex = firstIndexMatching($people, [
    'firstName' => 'Joe',
    'lastName' => 'Cool'
]);

The loop and the comparisons are moved out of the way and all the main part of your code need to do is supply the criteria for the search.

Ultimately after a search like this, you will want to have the item, not just its index. That’s easy enough, but don’t forget that if no match is found, array_usearch will return false, which php will often conflate with 0, so extra care has to be taken when using the returned index.

$joeCool = $joeCoolIndex !== false ? $people[$joeCoolIndex] ?? null : null;

Obviously this could be added to the firstIndexMatching function if one is never interested in the index itself.

And there you have it! A simple callback-based search function, ready to keep your main code clean and clear.

2

Thanks!

Forward to the Past

Posted on by
4

I’ve spent the last few days learning Ember, which is a software framework for making apps that run in your browser. It’s fun to learn new things, and it has been fun to learn Ember, which to me is a less-awful-than-most javascript framework.

(Things are going to be technical for a bit; please stand by for the rant that is the foundation of this episode — which is also technical.)

The good news: I have never taken a tutorial for any framework on any platform that put testing right up front the way Ember’s did. That is magnificent. The testing facilities are extensive, and to showcase them in the training can only help the new adopters understand their value. Put the robots to work finding bugs!

Also good news: Efficient route handling. Nested routes that efficiently know which parts of the page need to be redrawn, while providing bookmarkable URLs for any given state is pretty nice.

But… I’m still writing html and css shit. WTF?

Yeah, baby, it’s ranting time.

Let’s just start with this: HTML is awful. It is a collection of woefully-shortsighted and often random decisions that made developing useful Web applications problematic. But if your app is to work in a browser, it must generate HTML. Fine. But that shouldn’t be my problem anymore.

When I write an application that will run on your computer or your phone or whatever, I DON’T CARE how the application draws its stuff on the screen. It’s not important to me. I say, at a very high level, that I expect text in a particular location, it will have a certain appearance based on its role in my application, and that if something changes the text will update. That’s all.

I don’t want to hear about html tags. Tags are an implementation detail that the framework should take care of if my application is running in a browser. Tags are the HOW of my text appearing where I want it. I DON’T CARE HOW. Just do it!

When I came to work in my current organization, the Web clients of all our applications were built with a homegrown library called Maelstrom. It was flawed in many ways, being the product of two programmers who also had to get their projects done, and neither of whom were well-suited for the task of ground-up framework design (in their defense, the people who invented HTML were even less qualified). But Maelstom had that one thing. It had the “you don’t have to know how browsers work, just build your dang application” ethos.

There was work to be done. But with more love and a general overhaul of the interfaces of the components, it could have been pretty awesome.

Why don’t other javascript libraries adopt that approach? I think it’s because they are made by Web developers who, to get where they are, have learned all the HTML bullshit until it is second nature. The HOW has been part of their life since they were script-kiddies. It’s simply never occurred to them that the HOW should not be something the app developer has to think about.

There have been exceptions — SproutCore comes to mind — but I have to recognize that I am a minority voice. Dealing with presentation minutiae is Just Part of the Job for most Web client developers. They haven’t been spoiled by the frameworks available on every other platform that take care of that shit.

My merry little band of engineers has moved on from Maelstrom, mainly because something like that is a commitment, and we are few, and we wanted to be able to leverage the efforts of other people in the company. So our tiny group has embraced Ember, and on top of that a huge library of UI elements that fit the corporate standards.

It’s good mostly, and the testing facilities are great. Nothing like that in Maelstrom! But here I am, back to dealing with fucking HTML and CSS.

1

Thanks!

Blogtober Idea: Finish Something

Posted on by
1

Long ago I toyed with a frivolous serial fiction piece here called Feeding the Eels. It started as a parody of the noir genre, but gradually resolved into an homage.

I thought, what better way to get back into the fiction groove that pound out the conclusion to a story that had as a constraint that I spend a limited amount of time on each episode?

Eels had some pretty great moments as well, as far as I recall. It would be super-satisfying to actually finish something.

It’s been long enough, however, that I don’t remember all the ins and outs of the story. I was starting to tie up loose ends, but boy did I introduce a lot of factions in the early going. I clicked the category link in the sidebar and started reading.

So many comments on some of the episodes! There was an actual following for the story. A small following, but bigger than I usually get. I started reading, from the throwaway first episode (you can skip that one if you decide to read it) up to Episode 15: Year of the Rat. Next was Episode 14. Um… what?

Then 13, followed by 12.

Somewhere in the past I did some hijinxery to make the episodes in that category go from oldest to newest, with is anathema for blogs in general and WordPress in particular. Unfortunately, whatever I did is not compatible with the WordPress infinite-scroll feature of my current theme.

There is, at this time, no way to read past episode 15. Big Surprises and Heartbreak are soon to follow, but until I do some coding, it will be hidden. Suddenly my fun writing idea is dependent on a programming task. Sigh.

It’s worth doing, however; so tomorrow will be a technical day as I perform some server software upgrades and try to remember how I got the fiction categories going in the other direction, and how to make that work with infinite scroll.

Then over the course of October I will finish a story. And that will feel really, really good.

3

Thanks!

Defensive Programming: Put the Guards Near the Gate

Posted on by
2

We can file this one under “not interesting to pretty much anyone who reads this blog,” but it’s an important concept for writing robust code. This is part of a discipline called Defensive Programming.

Let’s say you build yourself a castle in a clearing in the woods. There is one path to the front gate, and you need to guard it. “Hah!” you think, “I’ll put the guards where the path comes out of the woods, to stop shenanigans before they even get close!” You post the guards out there in a little guardhouse, secure in the knowledge that no bad guys will reach your gate.

Until someone makes a new path. Perhaps when the new path is created the path-maker will notice that there are guards on the other path and put a little guardhouse on the new path as well. But perhaps not.

In software, it’s the difference between code that says, “when all conditions are right, call function x”, and having function x test to make sure everything is OK before proceeding.

Putting the guard by the trees:

    function x(myParameter) {
        myParameter.doSomething();
    }

    thing = null;

    ... other stuff that might or might not set 'thing'

    if (thing != null) {
        x(thing);
    }

This is fine as long as everything that calls function x knows to check to make sure the parameter is not null first. It might even seem like a good idea because if ‘thing’ is not set you can save the trouble of calling the function at all. But if some other programmer comes along and doesn’t know this rule, she might not do the check.

    // elsewhere in the code...

    anotherThing = null;

    ... other stuff that might or might not set 'anotherThing'

    x(anotherThing); // blammo!

Better to move the guards close to the gate:

    function x(myParameter) {
        if (myParameter != null) {
            myParameter.doSomething();
        }
    }

Now when someone else writes code that calls function x, you can be confident that your guards will catch any trouble. That doesn’t mean you can’t ALSO put guards out by the edge of the forest, but you shouldn’t rely on them.

2

Thanks!

Pretty Badass…

Posted on by
Reply

I just put the following comment in my code:

// now SHIT GETS REAL

3

Thanks!

Help Wanted

Posted on by
2

Anybody know a kickass Web engineer looking for work? I’m happy to discuss specific technologies and whatnot with anyone who might be interested.

Thanks!

Numbers, English, and Lazy Programmers

Posted on by
Reply

While doing research for an episode you will likely see shortly, I went to YouTube and did a search. This is what I got back:
Screen Shot 2014-06-11 at 10.46.47 AM
Note that it says I got “About 1 results”. Obviously, “results” is incorrect. There’s only one result! And About? What’s the standard deviation on that result?

This from a company that was bought by Google for a billion dollars or so. You’d think they’d have someone who could spend five frickin’ minutes to put in

if (results.count == 1) {…“

and to only include the word “About” when the code rounds off the number of results (which it does for very large result sets). Neither of those things should be difficult, and I’d be embarrassed if my program were so sloppy. Yet there it is on one of YouTube’s most oft-loaded pages.

MapMyRide.com made a bit more of an effort, but didn’t test all the cases:
Screen Shot 2014-06-08 at 5.13.22 PM

11st place! The rule that works for 1 and 21 doesn’t work for 11. Crazy English and the words we have for the low teens. I sent off a friendly report to MayMyRide letting them know; the bug was in a new feature, and MMR doesn’t have the resources that YouTube does. We’ll see if they fix it before I fall to 13rd place.

3

Thanks!

Esoteric Programming Languages

Posted on by
1

Most readers of this blog are probably familiar, at least by name, with some of the more common programming languages out there. This blog is brought to you courtesy of PHP, and then there are the seminal C and FORTRAN (after all these years, still king of the number-crunchers), the infamous COBOL, well-structured PASCAL, ground-breaking SmallTalk, Sun’s heavily-marketed Java and Microsoft’s counterploy C#, and newcomers like Ruby and Javascript.

There are a lot of computer languages. While there are some pretty striking differences between the above, they all have two things in common. They all involve controlling a computer by writing lines of code, and they were all invented to be useful.

There is another category of language that is not burdened by that second attribute. Useful? Pf. Not bound by the constraints of utility, the whole ‘lines of code’ thing often ceases to apply as well. These non-utile outliers fall under the general category of “esoteric language”, sometimes shortened (but not by me) to esolang.

While I have long been peripherally aware of this category of languages, in a small email discussion recently a friend of mine mentioned the language Brainfuck (sometimes written b****fuck to avoid offending people). Another member of the discussion linked to an amusing top-ten list of odd languages. I read the article and my brain started fizzing.

A programming language that is written as a musical score? Blocks of color that simultaneously convey quantity and program flow*? A program specifically designed to be as difficult as possible to write code in?

Some might ask, “why would anyone bother with such useless languages?” I don’t have an answer to that. I could go on about Befunge and the wire-cross theorem, or about Turing Completeness, but at the end of the day, I think it’s the same answer as one might give to the question “why does one bother writing poetry, when prose is so much clearer?”

Some of the languages are just for fun. INTERCAL (Compiler Language with No Pronounceable Acronym) set out with only one goal: to not be like any other language. For instance, since all coders have long been taught to avoid the GO TO command, INTERCAL instead uses COME FROM. And every now and then you have to say PLEASE. You don’t have to be a geek (but it helps) to enjoy this article about INTERCAL and Befunge (includes a Befunge program to generate Mandelbrot sets).

One can only read about esoteric languages for so long before one must scratch the itch and find a new way to write “Hello, World!” on a screen. I became intrigued by Befunge, a language that is not written as lines of code at all, but as a grid that a pointer moves around on, steered by >,<,^, and v characters. The program appealed to me for two key reasons: the characters the program cursor encounters can mean different things depending on which direction the cursor is moving at the time, and, even better, you can have the program alter itself by changing the characters in the playfield. So, here’s my Hello, World! in Befunge:


         095*0     v          0*59    <      
This 'Hello World' program is written  in Befunge, a
  language invented expressly to be as difficult to compile
  as possible.
 
 In fact, with this code, control flow  goes straight through
 this block of text and uses the p in  'program' as an instruction.

                                      +
v      g0*59       <                  1
     >                            "H",^
>:0-!|
v    <
     >                            "e",^
>:1-!|
v    <
                 > "0"+292*p >    "l",^
     > :6*9- :9`!|
>:2-!|           > $         ^
v    <
     > 7"0"+273*p                 "o",^
>:4-!|
v    <
     >                            " ",^
>:5-!|
v    <
     >                            "W",^
>:6-!|
v    <
     >                            "r",^
>:8-!|
v    <
       >                          "d",^
>:52*-!|
v      <

              v<
              " 
>:65+-        !|
              "
v  "error!"$   <
>:#,_         v

   restore the code to the starting state:
              > "2"292*p  "4"273*p @

Of course, it was absolutely required that the code alter itself at least once, and occasionally have the same symbol mean different things. This program is based on a counter, and when the counter is 0, it outputs an ‘H’. When the counter is at 1, out comes an ‘e’. ‘l’ is a little more complicated; after it matches the 2, the program does a little algebra (6x-9) to come up with 3, with which it then overwrites the 2 in the code. That way, on the next loop, when the counter is 3, we get another ‘l’, and the same equation replaces the 3 with a 9, ready for the ‘l’ in ‘World’.

In the language, ! means ‘not’. At the very bottom, this code evaluates the ! as ‘not’, which causes the program to loop around and pass through “!” (with quotes), turning what had been a program instruction into the exclamation point at the end of “Hello, World!” A nice little exclamation point on my program, as well.

I have now gone back and added an error message should something go wrong, but of course you have to alter the code to make an error actually happen, things being deterministic and whatnot.

You can watch the program execute in Super Slow-Mo with this Javascript Befunge interpreter. It’s kind of fun to watch the Instruction Pointer zip around the code. Paste the above code into the top box, click ‘show’, then click ‘slow’ below. I recommend setting the time to 50ms rather than the default 500.

Wooo! Big fun! While this language is nearly useless for actually accomplishing anything, I like the way you can make your code physically resemble the problem you are solving. A coworker mentioned writing a tic-tac-toe program with Befunge, and I immediately thought of building a program that is a grid of nine segments and the program alters the paths through the grid as moves are made. It would be awesome.

If I went back to college and majored in computer science, I could get credit for writing it.

In my wanderings, there was one program that completely blew my mind. You remember Brainfuck? There are only eight commands in that language, which makes it relatively simple to write an interpreter. An interpreter is a program that reads the code and executes the instructions as it encounters them, translating them from the (allegedly) human-friendly programming language into machine-friendly instructions for that particular processor. (Compilers do all the translating at once, before the program is executed, while interpreters do it on the fly.)

So here, ladies and gentlemen, is a Brainfuck interpreter, written in another esoteric language, Piet:

piet_bfi
(courtesy Danger Mouse — if I’m not mistaken, the inventor of Piet)

That picture right there? That’s a program, written in a Turing-complete language, that implements another Turing-complete language. (**)8-O (the sound you heard was my head exploding.)

______

* In Piet, you can write a program to calculate pi that is a circle.

4

Thanks!

How to Make a Geek Happy

Posted on by
1

I once explained in great detail why HTML is the worst thing that ever happened to the Internet. In that episode I was a bit disingenuous — I also snuck in flaws with the protocol that delivers most of that HTML rubbish to your computer: HTTP.

Finally, finally, twenty years later than necessary, the tools are available to make Web applications work like all the other apps on your computer. (If you’re willing to set down your browser, World of Warcraft and its predecessors have been doing this for a long time now. But finally we can have good application design through the browser as well.)

While the primary benefit of this revolution is for the engineers making the apps (whom you as a user have to pay eventually), there are tangible benefits for Joe Websurfer as well. Mainly, things will work better and be snappier. You will curse at your browser about 30% less. (That number brought to you courtesy of the dark place I pulled it from.)

I work in a blissful world where my stuff doesn’t have to work on older browsers, and especially not on Internet Explorer. That means what might be ‘bleeding edge’ for most Web developers is merely ‘leading edge’ for me. I’m starting a new Web application, and it won’t use HTTP. It won’t even use AJAX.

Quick description of HTTP:
Your browser asks the server for something. The server gives it to you, then forgets you ever existed. This is especially crazy when you want your connection to be secure (https), because you have to negotiate encryption keys every damn time. That’s huge overhead when all you want is the user’s middle initial.

And what if something changes on the server that the page showing in the browser should know about? Tough shit, pal. Unless the browser specifically asks for updates, it will never know. Say that item in your shopping cart isn’t available anymore — someone else snapped up the last one. You won’t know your order is obsolete until you hit the ‘check out’ button. The server cannot send messages to the page running in your browser when conditions warrant.

Lots of work has gone into mitigating what a pain in the ass that all is, but the most obvious solution is don’t do it that way. Keep your encrypted connection open, have each side listening for messages from the other, and off you go. The security layer in my new app is so much simpler (and therefore sturdier) that I’m going to save days of development. (Those days saved will go straight to the bottom line at my company, since I’m an operating expense. The effect of my app will also go straight to the bottom line, as I save other people time and energy. Better yet, the people who will be made more efficient are dedicated to making the company more efficient. Those days of development time saved go through three stages of gain. Shareholders, rejoice.)

So, that makes me happy. Web Sockets, event-driven servers, a chance to create the Missing Middleware to make the tools out there fly. Bindings over the wire.

Of course, I’m not building it all from scratch; I’m using and improving tools created by those who have gone before me into this ‘software working right’ revolution. It means picking up a whole toolbox at one time, from database to server to client library to extensions of all of the above. There are times while I’m trying to put it all together that it feels like my head is going to explode. In a good way.

But boy, the difference a good book can make. In technical writing, there are two kinds of documentation: tutorial and reference. Mostly I gravitate toward reference materials: I have a specific question and I want to get a specific answer. References are raw information, organized to allow you to get to the nugget you need. Tutorials are training documents; they take you through a sequence to help you build complete understanding of a system.

There are many technical documents that try to be both, or don’t know which they are. We call those docs “shitty”. Then there are videos. SPARE ME THE FUCKING VIDEOS. Videos as a reference: completely worthless; videos as a tutorial: rarely adequate – what was that again?

(I’d be interested to hear from my formally-trainied tech writer pals about my above assertions.)

Anyway, On the client side I’m using a library called Backbone, and on top of that Marionette. I like them, but I was starting to get lost in the weeds. The reference material is pretty good, but getting an overall understanding of how the pieces worked together was slow and frustrating. Too many new ideas at once.

So I found a book endorsed by The Guy Who Made Marionette (yeah, The Guy. One guy, having a huge impact on the next generation of Internet applications. Could have been anyone, but there had to be The Guy.) that not only puts the pieces together, but introduces best practices and the reasoning behind them along the way. It may well be the best tutorial-style documentation I’ve run across in this industry. So, hats off for Backbone.Marionette.js: A Gentle Introduction. This book really helped me get my ducks in a row. My fastest learning curve since Big Nerd Ranch oh so very long ago.

So all that makes me a pretty happy geek. Lots to learn, Web applications built right, a new project with lots of creative freedom. And while I’m coming up to speed on the new tools, I already see gaps — the tools are young — including a potentially ground-breaking idea, that I will get to explore.

Can you believe they pay me to do this?

1

Thanks!

Lost in Translation?

Posted on by
6

Even if you’re not a programmer, take a look at the following lines of code:

public function sendCommunication($oCommunication)
{
    if (self::emailMode != EMAIL_TEST_MODE_NONE) {
        if (self::emailMode == EMAIL_TEST_MODE_LOGGED_IN_ONLY) {
            // DO NOT COMMENT OUT THE FOLLOWING LINES
            // EVER
            // FOR ANY REASON
            // INSTEAD CHECK THE TEST MODE AND SET THE ADDRESS FIELDS ACCORDINGLY
            $oCommunication->to = $oCommunication->from;
            $oCommunication->cc = '';
        }

Now, I ask you, even if you’re not a programmer, you know there’s one thing you would never, ever, do to the above code. Right? Now let’s say you are a programmer, a professional, being paid because of your ability to find solutions to problems and express them in an abstract language.

Now further imagine that changing the above code can lead to the customers of the people paying for this work getting spammed with confusing emails with our client’s name on them.

Yeah, you guessed it.

1

Thanks!