True confessions about documentation
We’re waiting by the phone, um, computer to find that our Kickstarter project is (we hope!) approved. In the meantime, our Chief Marketing Officer asked me why there was a need for documentation, which is one of the expenses that would be funded from the crowd.
It’s like this – we started writing a game and we had certain deadlines to meet. We’d promised to have a playable game in the school by October. And we did. And the kids really liked it. And their math skills improved.
In the process, though, we did everything that had to get done to meet those deadlines and other things had to be put off until later.
Version control – later. User’s manual – later. FAQ – later. Anything that wasn’t promised was put on a backburner while we kept our promises.
And now …. we have code written in C#, PHP and JavaScript. There are SAS programs that were used to analyze the data. All of it was written by three people, 90% of it by just two of us. We have files in folders all over the place, on our server, on our desktops, on laptops. I know that one has the sound files, one has artwork used in the main 3-D game and some others have mini-games that are sort of side quests – but it’s not written down anywhere. We have a MySQL database and I know where it is, why we have it and what is in which table – but it’s not written down anywhere.
We have scripts that validate the answers students give to each question and then route them to the appropriate place – either back to play the game or to a site to study whatever math concept they missed. I know what those scripts are named and what they do – but it’s not written down anywhere. The Rocket Scientist has written a lot of C# code for the 3-D world and I know where the latest version is – but it’s not written down anywhere. I also do NOT know where the previous version is (although I could probably guess, or I could go upstairs and ask him).
My point is that we can’t go past the current level of complexity without documenting everything we have done up to this point or we are going to be royally screwed because:
- The further in time we get from when we wrote the first few game levels, the more likely we are to FORGET where stuff is and have one hell of a time fixing any bugs that come up because we won’t be sure what exactly File X does or where the script that does Y is saved.
- As we write new levels, we probably want to re-use code that does certain things like making the character do a little dance to pow-wow music, but we won’t quite remember why we wrote that bit in the middle, so, best leave it in – this is how one ends up with spaghetti code that is impossible to really maintain as no one knows exactly what it does.
- We are getting to the point of scaling up. This means bringing on another programmer or two. That future person is going to need to know where stuff is and what it does.
The truth is that we need to stop and write stuff down before we go any further. It’s kind of like when you are in college and you forego cleaning your apartment because you have to work and study for finals. Well, after finals are over, there is a point where you need to buckle down and clean your place before the fungus on the dishes in the sink evolves, forms its own government and evicts you.
What will anyone who donates to our eventual (we hope!) Kickstarter project get out of this? In front-end visible terms, they will get an on-line, downloadable user’s manual in pdf and html that explains how to play the game, all the levels, has an index to find answers to questions. We think you could probably figure everything out from playing the game, but some people like to read, and lots of people get stuck some times. We’ll have a Frequently Asked Questions page up on our site, and answers (since just the questions aren’t too helpful), for those people like me who don’t want to read a whole manual but just want an answer.
We’ll have a technical support wiki that you won’t see directly but which will help you indirectly because if you do run into a question not covered on our FAQ or a bug that needs to be fixed, one of us will be able to answer it a whole lot faster and better than, “Your guess is as good as mine” or, the one that always drives me crazy, “Well, it works on my machine.”
The other way documentation will help our supporters is that we really won’t be able to progress much farther nearly as fast without it – again, think about your post-finals trashed apartment. Eventually you realize that you are spending more time looking for your keys and cell phone than it would take to clean the place up.
So…. that is why we need funding for documentation.