My Obsession With Design Documents
Design documents are an important part of writing software. How important? So important that Jesus used the software design process in one of his parables!
28: For which of you, intending to build a program, sitteth not down first, and counteth the requirements, whether he have sufficient time and skill to finish it?
29: Lest haply, after he hath written much code, and is not able to finish it, all that behold it begin to mock him,
30: Saying, This man began to code, and was not able to finish.
OK, I may have paraphrased that a bit. But you get the idea. The first step in a successful project is sitting down and deciding exactly what you’re trying to accomplish and then figuring out whether or not it is actually accomplishable.
Careful planning also gives you a chance to notice problems while they are still theoretical and easy to fix. Realizing that you need to add sound effects to a program that is 99% complete requires you to rewrite and debug painfully large amounts of code. But if you realize that you need sound effects during the planning stage you can naturally add them into the code as you work. Much easier.
Example: The Chatbot That Probably Would Have Never Been Finished
Now it’s time for a real life example of how good design documents made my life easier.
When I first started this Let’s Program the one big question was what exactly my chatbot should chat about. Usually when I can’t figure out a topic for a practice project I default to table-top fantasy gaming on the basis that most computer geeks have played Dungeons and Dragons, played a Dungeons and Dragons inspired computer game or at the very least seen a fantasy movie where people hit monsters with swords.
So my first idea was to create a chatbot that could help Dungeon Masters design new adventures. A chatbot that could talk about plot hooks and dungeons and even automatically generate treasure hordes and room descriptions.
And I was so excited by this idea that I was very tempted to just jump straight into playing with code. But I resisted the urge and spent some time doing a nice requirements write-up for all you lovely people in the audience. And during that write-up I realized that I didn’t have nearly enough free-time to build this thing.
Writing a pattern-matching bot that can intelligently talk about fantasy adventures was going to be hard. Programming functions for generating treasures and rooms was going to be tedious. And linking input patterns to function calls instead of output patterns was going to involve advanced coding techniques that I felt would unfairly draw attention away from the simple “chatbot” focus I had planned for this Let’s Program.
So I’m saving that project for a future date.* Thanks to the power of design documents I’ve avoided an embarrassingly ambitious project and you’ve been spared the pain of watching me fail.
Design Document 2: The Fortune Teller Chatbot That I Can Build
I’ve already thrown away one project for being too complex for a good example of introductory chatbot design. What am I going to do instead?
Well, I’m going to write a fortune teller. Where by “fortune teller” I actually mean “random guessing machine”. The basic idea is to create a chatbot that can recognize when it’s being asked a question and then makes a wild guess at what the answer should be. If the user doesn’t ask a question the chatbot will prompt them to do so.
I also plan to make the chatbot as goofy and sarcastic as possible. Not only because I enjoy funny computer programs but also because the humor will hopefully disguise the fact that the chatbot isn’t actually smart enough to know what’s going on. But I’ll talk about that more in the future when I get to the ELIZA effect.
I shall call the chatbot DELPHI because I was an extreme mythology geek in my youth.
UI Design
The user interface is one of the most important parts of a good design document. It should include mockups of every page on a website, every screen on an app and a clear explanation of what every single button should do. It should give you a good idea of everything the user will be able to do and everything they should expect to see.
A good UI design can take up a lot of space!
But this is a text based program so our UI Design will only take a couple paragraphs. What a relief!
Official UI Design: The user opens the program via the command line. The program will print a line prompting them to begin communication. The user is allowed to type text. After they hit enter the program will generate a new line of text that responds to the user’s input as relevantly as possible.
Computer output will be proceeded by the string “DELPHI: ”.
User input will be prompted by the ‘>’ symbol.
Program Interface Mockup:
DELPHI: Welcome! What soul searching questions have you brought me today?
>Will Scott post his next Let’s Program soon?
DELPHI: The stars say it is very unlikely that Scott will post his next Let’s Program soon.
>Why not?
DELPHI: Because space aliens are interfering with the astrological radiation from Jupiter.
> You’re making that up.
DELPHI: I sense you’re not being honest with me. What questions do you really have?
>Goodbye
DELPHI: Until next time
Use Cases
Use Cases rank right up there with thorough UI design when it comes to valuable software development tools. For those few of you who aren’t familiar with the technique the whole point of use cases is to come up with a big list of how you expect your users to user your program. Then you write down what the program should do.
So let’s consider a few of the major question types we expect to see.
Use Case 1: Yes/No Questions
The most obvious questions that a fortune teller will encounter are those that have a simple yes or no answer. Most of these inputs will start with the word “Will”, “Is” or “Do” and end with a question mark. Example:
Will I get a promotion? Is my code bug free? Do androids dream of electric sheep?
In this scenarios DELPHI should respond with a randomly chosen positive or negative answer that includes appropriate portions of the user’s question. Example:
The stars agree you will get a promotion. Ether vibrations suggest it is impossible that your code is bug free. Fate calculations show that androids dream of electric sheep.
Use Case 2: Why Why Why Why?
Another popular type of question is the “Why” question. As in “Why won’t my code compile?”, “Why is the sky blue?” or “Why won’t my toddler stop asking me why questions?”.
In these scenarios DELPHI should respond with a randomly chosen excuse. The list of possible explanations should be large enough that casual users don’t catch on that answers are being chosen randomly. Explanations might include:
Because of the alignment of the stars. Because great Cthulhu is beginning to awaken. I would tell you but it is a secret to everyone. I used to know, but I forgot.
Use Case 3: A or B?
Users may ask DELPHI to choose between multiple options. This will be signified by the word “or” as seen in these sample inputs:
Should I buy a sports car or a motorcycle? Do I want chocolate or strawberry ice cream? Is that a moon or a space station?
In these cases DELPHI should generate a response that randomly agrees with the first or second option. By actually using the words first and second DELPHI will not need to actually include information from the original post. Consider these sample responses:
I've got a good feeling about the first one. My prognostication engine suggests the later. Definitely the former... assuming you trust Saturn.
Use Case 4: Goodbye
If the user types “Goodbye” the program will exit.
Default Use Case
It is very very likely that users will say things that do not fit any of our specific use cases. Especially if the user decides to not actually ask a question. In these scenarios DELPHI should generate a random response that urges the user to try again with a question. Possible responses might include:
Chatting is nice, but please ask me question instead. I'm bored. Go ahead, ask me why I'm bored. Sorry, I didn't hear you. What was you're question?
Conclusion
I feel like I have a really good grip on what DELPHI version 1.0 needs to do and I hope you do too. Which means the only thing standing between us and some actual programing is choosing an implementation language.
Three guesses what my next post is going to be about.
* Possibly after a zombie apocalypse has left me trapped in my own basement with nothing but months of bleak free time ahead of me.