Having a Title and Description
I was listening to the Stack Overflow podcast today. I was struck by something that seems like an obvious procedural thing that is so often missing from software projects: having a title and description. This is often called the 'elevator pitch.' Or, as the podcast calls it, a 'vision statement.'
The idea is to answer the question, "So, what are you doing?" or "What is your project about?" Here's a stab at a necessary and sufficient list of constraints on the answer to that question.
1. It has to be short. That is, think about it as the title and paragraph description on SourceForge, or the title and a snippet in a search result or in an RSS reader. The canonical 140 characters is a good upper limit.
2. It has to be written. Written like *written*. Like writers do writing. Not like "I put a bunch of ascii characters in a row."
3. It has to be concise and descriptive. More nouns and verbs than adjectives.
How come? First of all, it should be short because it should be easy to explain. It should be easy to explain because it should fit into the world in a way that is easy to explain. If it isn't, it is probably a waste of time.
It should be written in order to solve two problems. One is communicating it to people who aren't in the elevator with you. This also puts a proper scope threshold on the project. A project which isn't worth titling and describing is not a software project. It is something you should do with awk or grep.
The description should be mostly nouns and not many adjectives. This makes sure that you know what it is you are trying to do. The writing of this description commits you to some thinking. Fine. You may be wrong, but fortunately this needn't be your last project. You can change the description and try again.
These constraints imply a certain level of thinking and iterating and refining about what it is you are doing. That's fine. That's basically writing like writers do.