Specs from the beginning.

Three or four weeks ago I read on twitter about codecademy, an online tutorial website that steps people through learning to code in a fun manner. It makes learning to code a game like experience with badges for accomplishments. I've always been interested in programming. I've even mis-spent a year being a programmer during college (I'll explain that one sometime). So I signed up and completed the codecademy program, which uses javascript for it's tutorial language. Having worked through that I craved more. I knew what javascript was briefly about, but I was looking for more depth. While I could have explored jQuery or Node.js I opted to pick up a copy of Head First C# and take myself through learning to build applications for Windows and, hopefully, in the end, to develop a Windows Phone app.
I'm not a programmer, not by profession. I earn my living as a project manager and I think that has given me a different look at both the codecademy and the Head First book. They both have horrible spec writing.

It's not the actual writing that I'm talking about here. They're both well written and accomplish the tasks they set out, which is to make learning a programming language in an engaging manner. But they both suffer from bad specs in the projects they ask of the student. If the intention is to have a programmer learn with a later goal of accomplishing projects, then assume that some of those projects may not be their own. After all, we're not all start-up foundries. So while learning to produce a project one of the goals should be to turn specifications into code. This isn't possible if during any of these tutorials a specification is never presented in a clear manner. Codecademy does present a spec of sorts during the course of a project, in pieces during an example. It never presents it before the project, never gives the coder a chance to work through the problem in their heads before attempting to put bytes into the editor. Head First does a similar disservice here. Un-important while explaining some of the minor portions of the language it does the same during the larger projects (e.g. the race simulator project in Head First C#).

At first I thought I had it. I had two pages of explanation to step through in my head to come to an outline and idea of what the project code should look like. It was all rather simple from that point and, wanting to work through the problem in my head and think to a solution, I wrote out a project definition and started to put code in the IDE. I refused to turn pages to see sample code until I had tried myself. What a shock though when I finally did turn the page and there was more specs, a GUI was to be included, and this was after code explanations were already given for 3/4 of a page.

So, if we're going to ask future coders to translate written words into machine code it would seem that we should ask the instructors and text writers who teach coders to write complete specs and present them before showing how it's done. Otherwise we're not asking the coder to use brainpower to solve problems, which is the largest part of programming. To do otherwise is not only bad practice, but for most of the coders I know, it's nearly insulting.