Software is not Jewellery

Most requirements are written in isolation from the data from the market. But that is not always a good practice. Here is the Table of Contents of a typical software product requirements document where the market data is not neglected. Accompanying is an explanation of each head.

1 Table of Contents

This contains the table of contents

2 Purpose

This section enumerates the purpose of the application. It also points out, with as much clarity as possible, the people who will benefit from this application and how they will benefit from the same. This section is a short description of the environment, the intended users etc. In this section the service provided by the application under question will be enumerated. Whether the application will face competition in the market from similar services or from any other service will also be noted here. In this context, how the competition may be over come can be briefly described.

3 Part I

This deals only with the non-technical details of the project on which the technical details will be built.

3.1 Application Overview

Describes elementary details of the application under question. For example, weather, it is a web application or a static website or a windows application etc. If required, the problem (i.e. the business opportunity) in current context should be explained. This will help the development team keep their focus, decide which features are important and which are not. Secondly, it also help as the common ground between the development team, the marketers and the customers. This section will direct all parties involved throughout the lifetime of the project. This section also contains who the users are going to be and what are the deliverables.

3.2 Business Process

This section describes how the business process works in absence of this application. It is recommended this is written in collaboration with a user who is going to use the application in future. Detail in this section will help the developers capture the requirements completely. Consider the product under question is a mail application. Gmail for example. The business process under question is about “How written communication happens?” People buy paper, buy pens, buy stamps, buy envelopes, they have a table and a chair to sit and write. And they start writing. After they are done, they get gum. They enclose the letter, stick the stamps to the envelop, walk to the post box and drop it. This is the description of the business process called Written Communication. However, a mail application may also face competition from other mode of communication as well. Telephones for example! This could be noted as well.

3.3 Software Process

This section describes how the same business process will work in presence of the application. It will describe briefly how the application integrates in the business environment enumerating the advantages it will bring about in each step. For example most mail applications perform at least these two functions: 1. serve as a mail box and 2. a contact details list. The mail box brings about fast and inexpensive written communication and the contact details facilitates a mobile and weightless address book. So decreased costs, faster communication and data mobility are the advantages of a mail application. Such advantages need to be noted here. If the system interacts with other systems that will also be noted here. It is recommended this section is further broken down into smaller parts, each part describing a small part of the application under question.

3.4 System Requirements

This section will write down the minimum things the user needs to have in order to own this application. Gmail for example needs, a computer, a live internet connection and a Google account.

4 Part II

This part contains the technical details about how the application will be divided into separate parts and how it will be implemented. It is recommended that a few mock screen shots and a few system design concepts be described in some detail. However, it is important to to note that the development team may (and perhaps will) change the design expressed in this part. The intention behind these technical description is just to aid the understanding the developers. A mail application for example, can show a few screen shots of the mail box, or the address book, or the database tables it is going to use in the same. It may also want to enumerate a few encryption technologies if it feels that they are important.

5 Appendix

If there is anything you want to refer, put here.

Use Cases are actually stories told by a software designer about how he plans to accomplish certain goals in the software under question. Before the use cases are written the requirements document should be ready. Its time for the software designer to conceptualize. He will imagine. For example if you want to log in to a certain application the following will have to be done

1. Open the application
2. Login page is displayed
3. User enters user name and password and clicks on OK
4.User name and passwords are authenticated
5.User’s home page is displayed

This use case can be called “Login”. The sequence of steps above enumerate what the user does and how the software reacts to that. You identify a certain goal, called “Login” in this case, and conceptualize how it can be achieved. This is a use case. Of course in the above use case you could have just written

1. Open Application
2. Enter user name and password and press OK

However that talks only of what the user is doing. You have to go under the hood and think of what the software will have to do under those conditions. For example as soon as you write the step, “User name and passwords are authenticated”, you know that you have to have an authentication procedure. That means you have store your user names and passwords somewhere. Straight away you get one data structure to put in our design document. This way you have already started listing the Data Structures. Ideally if you are writing good use cases you can simultaneously work on the other parts of the design namely Presentation Layer, Data Layer and Logic Layer. When you write a Software Design Document, you first start out with writing the indexes. Then you start writing the use cases. When you write use cases you use your imagination and experience as a software guy to imagine how a particular goal can be accomplished. You think of what the user will do and what the software will do and then you get ideas on design. And you keep filling the rest of the document as you go. Given below is a use case template I used for a software project I am current working on.

Use Case Template and description

Use Case                    Contains the name of the use case

 

Goal Description       Contains a brief description of the use case

 

Preconditions      Contains what should be the state of the some important factors before this use case should commence

 

Post Conditions    Contains what would be the state of the some important factors after this use case completes

 

Technical Issues       Contains any technical or user issues on this write it here

A lot of new paradigms in Software Development have questioned the usefulness of Use Cases. But, I have always found them really helpful and handy.

There are some issues here. Navigating across one view and the other is always a matter of choice. You see, there are lot of ways of navigating across a software. Some of them are

1.Menus
2.Nested Menus and Context Menus
3.Tabs and Tabs Inside Tabs
4.Keyboard Shortcuts
5.Tool Bars

Right now I cant think of any other way one can navigate across applications. But I bet myself a hundred bucks, there are plenty of them. So you got to think, what will you use for navigation. You choose one of them. Why? what are the advantages? what looks better? which is easier etc etc. You’ve gotta think it all out. For example, you see if you are using a menu and only a menu to navigate across an application, you’ll need at least 2 mouse clicks to get to some other page, one click on the menu and the other on the menu item that names the page. Take a look at this scheme at flickr

Here I click on Contacts then I can see all these pages Latest Photos, Contact List, People Search, Invite Your Friends and Invite History. Then you choose one of them and you go to that page. There is also a Nested Menu where menus are built inside a menu item. I don’t really know what purpose they serve other than just giving access to a lot of functionality.

But menus can be irritating when you are moving from one page to the other very fast. For instance, when you are surfing the net. To solve this Mozilla introduced Tabs. It was great success. I am not sure if they were the first guys to realize the importance of a Tab but anyways, have a look.

Here you need only a single mouse click to navigate across the different views. That is very good when you are flipping through information at a very rapid speed. Surfing the net is a great application for that. If you notice, Mozilla has both menus and tabs. And different navigation items give access to different functionality! The Tab thing caught on so well that even Microsoft started using it in IE 7! Whats more people started using Tabs inside tabs. Check out this wordpress interface.

Here one has lot of child tabs to parent tabs. So to get to Manage->Categories, you’ll have to go to Manage first, the default Tab i.e. Posts will load first and then you get to Categories. The problem with this is that since every Parent tab WILL have a default page, the software loads two pages before you get to the page you really wanted. But let us say that 90 percent of the time, you need the Posts page in the Manage parent Tab. Then this this is OK. Not the most efficient, but OK. In such a case Menu always works better.

Of course there are also nested menus and Context menus. Here is a nested menu.

Apart giving user access to functionality they are not going to use so often, I don’t seen any other use of these. The point is you have a software with a lot of features, Microsoft Word for example. And you have to give the user some kind of access to that functionality right. And you cant cramp all of it in one menu. So you use a nested menu.

And finally the context menu. A context menu is nothing but the the menu that pops up when you right click on something. Depending on where your mouse was positioned during the right click, you give access to different functionality. This is a cool idea. In Windows if you right click on your desk top, you get this.

However, if you right click on a item ON the desk top, you get this

So depending on where the user has clicked, you can give him access to different functionalities. This is a very powerful way of deigning useful User interfaces.

I think.