Introduction
There’s plenty of information on the Internet about how to write code, how to develop software and web sites, and even how to market your project once it’s done. So what’s missing?
One of the most important and often time consuming steps in the development process is planning. There’s little doubt that detailed specifications of what your project will do and how it will be built will greatly reduce the time and complexity of the development, testing, and maintenance.
Without a systematic approach to writing detailed plans for a project, it often seems much easier to jump into development and start prototyping with little or no planning at all. This often leads to rewriting sections of code that don’t quite achieve the goals, or even the whole project becoming messy and inefficient.
With an easy, systematic way to write the plans, the whole development process becomes amazingly simple and efficient. It can also ensure that the end product does exactly what it’s supposed to, with little or no additional guidance from the owner or client.
This article intends to make the planning stage much easier than the development stage, and once it’s done, the development can, and usually will, just fall into place. Here’s the step-by-step guide…
Note: Keep in mind that the plans you write will undoubtedly change throughout the development stage. The plans are still invaluable as they document the changes made to any part of the application. All team members should have easy access to the latest version of the plans. Don’t bother trying to get your plans 100% perfect (unless you plan to hand it all over to another developer to take over) because you can add more detail as you go.
Project Summary
The first and simplest step is to write up a summary of what the project is for. This shouldn’t be more than a couple of paragraphs. Just imagine you have 5 minutes to tell someone what you want to build, just to give them a very basic idea.
Example:
Blog Manager Summary
The blog manager will allow multiple users (designated by the administrator) to log in to a secure administration section to add a new blog post every couple of days. The blogs will be displayed on the web site for visitors to read, and for search engines to index. |
Project Goals
The second step is to note down the overall goals of the project. This is the checklist to know when the project is complete.
The easiest way is to list them as points.
Example:
Blog Manager Goals
- Administrators must be able to create and manage accounts for users.
- Users must be able to edit their own account.
- Users must be able to log in to post or edit their blogs.
- Administrators must be able to review and manage blog posts (to remove bad language, etc.).
- Managing users and blog posts must be secure.
- Visitors must be able to view the summaries of all the blog posts, then select a post to read all the information.
- Search engines must be able to crawl and index the blog posts.
- Visitors and email spiders must not be able to see users’ email addresses.
|
Project Features
The third step is to outline each feature that the project will include. Up to a couple of paragraphs can be used to describe the details of each feature.
The information for each of these features will become more detailed as you go through each of the following steps.
Example:
Blog Manager Features
Users
Administrators can log in to create and manage user accounts. Users can log in to edit their own account.
Blog Posts
Users can log in to create and manage their blog posts. Visitors can view the latest public posts. |
Feature Actions
The fourth step is to list and define everything that can be done within the project, relating to each feature. Additional information can be noted down beside the actions to describe some constraints when performing the action, but some are fairly obvious and require no explanation.
If you prefer Use Case diagrams for defining your feature actions, you can export the diagram into this section of your plans.
Example:
Blog Manager Features
Users
Administrators can log in to create and manage user accounts. Users can log in to edit their own account.
Actions:
- List users (admin)
- Create user (admin)
- Edit user (admin)
- Delete user (admin)
- Login (user)
Blog Posts
Users can log in to create and manage their blog posts.
Actions:
- List blog posts (user)
- Create blog post (user)
- Edit blog post (user)
- Delete blog post (user)
- View public posts (visitor) – Displays summary of all posts, latest first.
- View public post (visitor)
|
Feature Attributes
The fifth step is to list the attributes that will be related to each feature.
If you prefer UML Class diagrams for defining your feature attributes, you can export the diagram into this section of your plans.
Example:
Blog Manager Features
Users
Administrators can log in to create and manage user accounts. Users can log in to edit their own account.
Actions:
- List users (admin)
- Create user (admin)
- Edit user (admin)
- Delete user (admin)
- Login (user)
Attributes:
- Username
- Password
- First name
- Last name
- Email
- Bio
Blog Posts
Users can log in to create and manage their blog posts.
Actions:
- List blog posts (user)
- Create blog post (user)
- Edit blog post (user)
- Delete blog post (user)
- View public posts (visitor) – Displays summary of all posts, latest first.
- View public post (visitor)
Attributes
- Title
- Content
- Date published
- Author
- Views
|
Workflow Procedures
The sixth step is to describe how everything will be done. It’s up to you to decide how much detail you use for each operation. Too much detail will take too much time, and not enough detail may cause hassles during development.
The simplest way to do this (which can be used for most operations) is a numbered list of each step. This method doesn’t allow for too much dynamic complexity but it’s quick and easy to do.
Another common way to do it is to use workflow diagrams, such as in Microsoft Visio or Microgold WithClass. These can usually be exported and placed into your document.
It’s up to you to choose the appropriate level of detail for each operation, and whether to use just a list of steps or a detailed workflow diagram.
Just change the bullets under Actions into headings, and add the details under each one.
Example:
Blog Manager Features
Users
Administrators can log in to create and manage user accounts. Users can log in to edit their own account.
List users (admin)
Administrators can view a list of users.
- Log in
- Click “Users”
- Users index is displayed with name, email, number of posts, as well as an edit and a delete button for each.
Create user (admin)
Administrators can create users.
- List users
- Click “Create User”
- Enter user’s first name, last name, email address, username, password, bio
- Select whether the user is an administrator
- Submit
- User is created
Edit user (admin)
Administrators can edit any user.
- List users
- Select user to edit
- Edit user’s first name, last name, email address, username, password, bio
- Edit whether the user is an administrator
- Submit
- User is updated
Delete user (admin)
Administrators can delete any user.
- List users
- Select user to delete
- Confirm delete
- User is deleted along with all their blog posts
Login (user)
Users can log in to make posts.
- Go to site
- Enter username and password
- Credentials are validated and user is logged in
Attributes:
- Username
- Password
- First name
- Last name
- Email
- Bio
Blog Posts
Users can log in to create and manage their blog posts.
List blog posts (user)
Users can view a list all their posts.
- Log in
- Click “Blog Posts”
- Blog posts are displayed with title, summary, author, date, as well as an edit and a delete button
Create blog post (user)
Users can create blog posts.
- List blog posts
- Click “Create Blog Post”
- Enter post title, content, author, status (draft, published)
- Submit
- Post is created
Edit blog post (user)
Users can edit any of their posts.
- List blog posts
- Select blog post to edit
- Edit post title, content, author, status (draft, published)
- Submit
- Post is updated
Delete blog post (user)
Users can delete any of their posts.
- List blog posts
- Select blog post to delete
- Confirm delete
- Post is deleted
List public posts (visitor)
Visitors can view a list of all public posts, latest first.
- Go to web site
- Public posts are listed with summary, author, date published
View public post (visitor)
Visitors can view any public post.
- List public posts
- Select post
- Post is displayed in full
Attributes:
- Title
- Content
- Date published
- Author
- Views
|
To give you an idea of how workflow diagrams could be used, here’s an example of one for the Login operation. You’ll notice that it has a lot more detail, which is good for some cases, but for a typical login situation, it’s probably not worth the time.
Example Document
Here's a complete example requirements document. You'll probably have a lot more features in your application but you should still be able to detail most of it using this technique.
Blog Manager Requirements
Summary
The blog manager will allow multiple users (designated by the administrator) to log in to a secure administration section to add a new blog post every couple of days. The blogs will be displayed on the web site, for visitors to read, and for search engines to index.
Goals
- Administrators must be able to create and manage accounts for users.
- Users must be able to edit their own account.
- Users must be able to log in to post or edit their blogs.
- Administrators must be able to review and manage blog posts (to remove bad language, etc.).
- Managing users and blog posts must be secure.
- Visitors must be able to view the summaries of all the blog posts, then select a post to read all the information.
- Search engines must be able to crawl and index the blog posts.
- Visitors and email spiders must not be able to see users’ email addresses.
Features
Users
Administrators can log in to create and manage user accounts. Users can log in to edit their own account.
List users (admin)
Administrators can view a list of users.
- Log in
- Click “Users”
- Users index is displayed with name, email, number of posts, as well as an edit and a delete button for each.
Create user (admin)
Administrators can create users.
- List users
- Click “Create User”
- Enter user’s first name, last name, email address, username, password, bio
- Select whether the user is an administrator
- Submit
- User is created
Edit user (admin)
Administrators can edit any user.
- List users
- Select user to edit
- Edit user’s first name, last name, email address, username, password, bio
- Edit whether the user is an administrator
- Submit
- User is updated
Delete user (admin)
Administrators can delete any user.
- List users
- Select user to delete
- Confirm delete
- User is deleted along with all their blog posts
Login (user)
Users can log in to make posts.
- Go to site
- Enter username and password
- Credentials are validated and user is logged in
Attributes:
- Username
- Password
- First name
- Last name
- Email
- Bio
Blog Posts
Users can log in to create and manage their blog posts.
List blog posts (user)
Users can view a list all their posts.
- Log in
- Click “Blog Posts”
- Blog posts are displayed with title, summary, author, date, as well as an edit and a delete button
Create blog post (user)
Users can create blog posts.
- List blog posts
- Click “Create Blog Post”
- Enter post title, content, author, status (draft, published)
- Submit
- Post is created
Edit blog post (user)
Users can edit any of their posts.
- List blog posts
- Select blog post to edit
- Edit post title, content, author, status (draft, published)
- Submit
- Post is updated
Delete blog post (user)
Users can delete any of their posts.
- List blog posts
- Select blog post to delete
- Confirm delete
- Post is deleted
List public posts (visitor)
Visitors can view a list of all public posts, latest first.
- Go to web site
- Public posts are listed with summary, author, date published
View public post (visitor)
Visitors can view any public post.
- List public posts
- Select post
- Post is displayed in full
Attributes:
- Title
- Content
- Date published
- Author
- Views
|
Conclusion
Once you’ve documented all the features in your project up to this stage, you’ve completed your requirements document. You can give this document to your team so that they know exactly what the project will be able to do. You can use the document to get quotes from third parties for sections of the project that you’re outsourcing. Most investors would also like to see this document so they know exactly what they're investing in.
It is possible to develop simple applications without any further documentation. If you have experienced team members who work well, you may decide that a technical specification isn’t worth the time. The decision should also factor in the value of having a technical specification during maintenance, especially if the maintenance team changes.
Look out for the next article explaining how to write your project's technical specification.
John is the founder of SoftwareMonkeys (www.softwaremonkeys.net) and the creator of various open source projects including:
- WorkHub modular ASP.NET framework (and included project management/organization modules)
- SiteStarter ASP.NET base framework and libraries (reused in projects such as WorkHub).
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
