All projects start with, at the very least, a list of requirements; things the solution MUST do. This list can be formal, or it can be based on a
conversation with a project stakeholder. Sometimes the requirements are known, sometimes they need to be solicited from the users. Most people know it's NOT realistic to think you can gather every single requirement up-front, before any other work begins. Sometimes, the requirements that we do get are pretty vague and ambiguous and sometimes they are crystal clear.
We must be able to search for a customer by name, location, customer ID and by sales rep.
A sales rep may have one or more customers
We need to be able to print 50,000 notifications by the end of the month!
Once I have an idea of what the user wants, I'll do my best to document my understanding of things. This will include clarifying any of the requirements that are obviously too vague or ambiguous.
Documentation:
Scott Ambler said:
"It's important to recognize that you need to create just enough documentation when developing software -- too much not only sucks the life out of the project, but also puts your project at risk for failure. Not enough documentation is also dangerous..."
I've either led, or been a part of, many projects that tried to gather all of the requirements and write all of the designs (Big Up-Front Design - hereafter
BUFD) before starting any of the code. None of them met the kind of success that was expected. After all, if all the requirements are written before the
designs and all the designs are written before the code (and exactly to the spec/requirements), then writing the code should be the easy part, right? Not
in my experience. Apart from the fact that requirements almost always change, I've never met anyone (including myself) that did such a good job at design that NO questions came up during coding.
In fact, I left a project in 2004 because the project leader was driving the project into the ground by insisting on doing a BUFD. Of course,
two months before we were supposed to ROLL THE APP OUT, he was still tweaking the requirements and we were still churning out design docs (but not really writing any code).
My experience has pretty much always been that it is a good thing to gather as many of the requirements as possible before anything else. After that, flexibility is the key. I know things will change - it's guaranteed. Many times, my documentation will consist of a stack of index cards - each card will list a requirement and a possible list of steps to complete that particular requirement. I have written requirements documents that were nothing more than a hundred pages of bullet points. I have also written documents that were extremely verbose and easily understood by anyone picking it up.
My current “favorite“ way of writing documentation is to use MindManager. :-) It fits perfectly with the way I think, but it also allows quick and easy exporting to Word, Project, Powerpoint, etc. I can even manage tasks with it, but I digress. I'll write more on that later.
When it comes to documenting my designs, I tend to stick with the idea that the person writing the design should absolutely be the person that will write the code. Granted, I do want others to understand what it is I'm doing, but it's truly difficult to write a design document that someone else can pick up, look at and then start knocking out the code for.
I lean heavily toward prototypes when I'm designing: screenshots, pseudo-code, dummy data in the database, etc. I am also a huge fan of Test Driven Design/Development.
High-Level stuff:
Once I have at least some of the requirements, I'll start thinking about how my application(s) will look from a high-level. How will things be separated? Fat
client? Browser based? N-Tier? Will any web services be involved? Will I be connecting to any data sources out of my control? Is this a completely new
system or a modification of an existing system? Are there any (programming) language constraints? Again, I'll document the answers to my questions, but
I'll try not to overdo things.
Next stop: Part 1a - more on design activities