User story

Writing requirements is a very important aspect of software development process. Most often it is abstract and we get lost in details that are not so relevant and miss real data points that might be really required.

In agile methodology or in general, writing requirements in a format that is understood by every stake holder is very important.  Suppose I do lot of infragraphic work and complex document with too much of information (technical/non technical), client might say  "It looks good" and can sign off without reading the details.

A good Product Manager/Analyst is one who will make sure all details are captured sufficiently and are still readable  by any stake holder.   

User story is a best way I can think of, to represent requirements. A complex FRS (Functional Requirements Specification) PRD (Product Requirements Document) or any other jargon that is used to represent requirements might sound complex and not really undrestood well enough by all stake holders.

Let me write a user story that might help represent my version/view of how it(requirement) can be presented.

First the rules:

• Actors/Stake holders of the use case
• Pre-conditions
• Input data (provide all fields that are of interest to the business).
• Validations applicable.
• Complete steps of the use case
• Expected behavior (used for acceptance criteria)
• Alternate paths (if positive flow doesn't work, what other alternative work flows are possible)
• Optional steps if any.

User story - user registration

Actors 

System, User

Pre-conditions

• User visits the home page of the application
• Clicks on "Register" link/button

Steps:

1. When user clicks "Register", the registration form is shown to the user.
2. User need to provide the following data points.
1. Email - mandatory, should have valid email format validation
2. Confirm email - mandatory, should match with email
3. Password - mandatory. Should have minium 6 characters, 1 upper case, 1 lower case, 1 numeric values.
4. First Name - Mandatory
5. Last Name - Optional
6. Gender (drop down with male/female/do not want to reveal options) - Mandatory
7. Country - Mandatory. Show countries list in drop down. If possible pick up the country name based on the user IP/location.
8. ....
3. User fills all the data as needed and clicks "Register" button.
4. System validates if the user already has an account (can happen at 2.1 too through ajax call), if the user has an account (with same email), System will throw error  "This email id is already in use. You can try logging in. If you want to register with another email id, please modify".
5. All other fields are validated too. If everything is found OK, then user is registered in the system.
6. Password should be encrypted with no decryption possible.
7. An email is sent to the user with the following format.
1. Dear ${first_name}, Thank you for registering with <ApplicationName>. Please click <link> here to confirm your email address and to complete the registration.... <complete rest of the template >. Regards, Administrator <ApplicationName>
8. User email confirmation
1. If user clicks the email, his account is activated and can be logged in using the credentials provided during registration. 
2. If user doesn't click the "confirmation" link in email, then application should delete the account after 15 days. 
9. If there is going to be any other technical error, an email should be sent to support team to investigate the scenario. User should be shown a technical error message.  "Sorry, your registration has failed, There seems to be a glitch at the moment and our support team is informed about this error. Apologies"
10. Other alternative paths:
1. User fills the form, submits the form but there is an internet problem, so the request never reaches the server. User should be shown proper message to try again. 
2. Invalid data - user should be shown corresponding list of errors to rectification.
3. User fills the form, full or partial and decides to cancel registration. He clicks "Cancel" button and user should be shown a relevant message and login page be displayed.

Analysis

Well, the requirement looks pretty much good with lot of details, but it is possible that there may be questions during implementation and developers /testers might need to get clarifications on various things.  Product Manager should be available for clarifications required.

Please note the requirement is more functional and actual implementation might need to contain various additional aspects to be taken care, like

• Logging
• Validations
• Db design
• Transaction management
• Email logic implementation, have templates defined in db/files so that they can be edited independently.
• Technical documentation
• Unit testing

These additional stuff is not documented as part of the requirement (user story) itself, but still development team need to take care.

At the end, capturing details in a way that is understood by client, development team, managers etc is the most important thing.