Story Points

/in /by

Don’t use hours to estimate a requirement or feature.  Your estimate will be wrong, but you’ll be held to it.  Instead let’s use story points.  Story points are values that only have meaning within a given team.  That meaning is developed, learned, and refined over time.

 To understand story points, let’s look at something similar that we all understand.

Restaurants are rated on a scale of 1 to 5.  That star rating conveys a lot of information.  With that star rating you know the following:

  • Quality of food
  • Attire
  • Price
  • Wait time for food
  • Will there be valet parking?
  • Will there be a waiter or do I order at the counter?
  • How customizable will the meal be?
  • How knowledgeable will the staff be?

If I tell you we are going to a 5 star restaurant, I bet you could answer all of those questions with a high degree of confidence.  You would not know precisely how much it will cost, but you’ll have a ballpark feel for it.  If tell you we are going to a 2 star restaurant, again, I bet you have a pretty clear expectation.

If instead of the star rating, I just told you that the food was really good, would you know how to dress?  If I just told you that it was very reasonably priced, would know if you were ordering at the counter or talking to a waiter.  If told you that meals were $50 a plate, you might guess that it was a 4 or 5 star restaurant.  But in reality it could be a 3 star tourist trap on an island that has only 1 restaurant and has to fly all of their food in from the mainland.  The point being is that knowing only one dimension can sometimes you get close to the right answer, but can also be quite misleading and dangerous.

Story points allow you to embed information from lots of dimensions into the numeric value.  We might embed the following dimensions into our story points:

  • Coding effort
  • Complexity
  • Risk
  • Knowledge of technology
  • Quality of the domain expert
  • Platform
  • Usability requirements

So maybe we can setup story points like the following:

Example:

  • 1 point = easy, straightforward feature
  • 2 points
  • 3 points = moderate, somewhat complex feature or contains some moderate risk
  • 4 points
  • 5 points = hard, complex feature, that may contain high risk

These are just guidelines to get started.  Story points develop meaning over time.  Just as with restaurants, it took experience with restaurants before you understood the rating system.

In that one number you can embed any additional information or padding that you may need.  If you estimate everything in hours you will be challenged by people who don’t know better.  If you assign story points to things, you can use your intuition or any other knowledge to pad your estimate without getting into a debate with those who don’t understand.

Each developer will bring a different intuition to assign story points.  Some will be junior developers who spend most of their time focused on technology challenges.  Others will be senior architects who are assessing risks and future complexities far outside the experience of the junior developer.  Story points serve to normalize those large differences in experience and perspectives across the team.

Story points are a tool.  When used incorrectly you will get bad results.  Story points only work when the project is being managed in the Scrum (or similar) methodology. They work with time boxed sprints and user stories.  If you are doing time boxed sprints and user stories, then you may not get the desired results.

User Stories

/in /by

What is a user story?

A user story is one or more sentences describing what a end user needs.  It is expressed in everyday language or the business language of the user.  A user story is NOT intended to capture ALL knowledge required to implement a given feature.  User stories facilitate conversations between customer and developer.  The details required to implement the story are acquired overtime via these conversations.  

Why user stories?

  • Verbal communication – yields greater knowledge and understanding
  • Comprehensible (non technical)
  • Right size for planning
  • Work well with iterative development
  • Encourage deferring detail
  • Opportunistic development
  • Participatory design (between developers and customer)
  • Build up tacit knowledge

Structure of a User Story

As a {user role} I want to {do something} so that {reason} 

  • User Role = Who
  • Do Something = What
  • Reason = Why

 NOTE: we are not talking about HOW to implement it.

The structure of the sentence forces us to talk about requirements and NOT design.  This prevents us from short-circuiting the analysis and design phases.

Attributes of a good user story

Very good blog explaining the important attributes of a user story

http://agilesoftwaredevelopment.com/blog/vaibhav/good-user-story-invest

Just think of INVEST to remind you of the attributes of good user story.

  • Independent – loose coupling between user stories.  Makes planning much easier.
  • Negotiable – don’t design a solution or specify so many details that you paint yourself into a corner.  We should always be free to change our mind on HOW to implement the given requirement at a later time.
  • Valuable – must be a value to the end user
  • Estimable – must be able to put an estimated number of hours or days
  • Small – less than a week
  • Testable – so we know when we are done.

A useful tool for ensuring that user stories adhere to INVEST is to either break a user story apart into smaller user stories.  Occasionally, the opposite might be true (combine many smaller use stories), especially in support of Independent.

Drawbacks to User Stories

  • Difficult to understand relationship between stories
  • May require augmenting them with additional documentation if traceability is a mandate
  • May not scale well to large teams (too much conversation and too many pathways)

Guidelines for Good Stories

  • Start with Goal Stories – why is user using the system?
  • Slice the Cake – slice up large stories in way that the user can actually accomplish something (not part of something).  e.g. 1) collect data 2) write to database.  That is bad.  Good would be to 1) collect basic information, 2) collect detailed information
  • Write closed stories – don’t write a story that will never complete.  e.g. A user can manage his projects.  instead, breakup into smaller chunks that can be completed.  e.g. A user can add and remove team members from a project.
  • Put constraints on cards
  • Size the story to the horizon – stories you are going to tackle sooner need more precision.  Stories far in the future don’t need same level of precision.
  • Keep the UI out as long as possible – that’s a design task, not a requirements task
  • Some things aren’t stories – if it does not fit in a user story, use a different method.  Use this is a last resort, not as a cop out to learning how to write good user stories.
  • Include user roles in stories
  • Write for one user
  • Write in active voice
  • Customer writes – ideally, but requires training and discipline on the part of the customer
  • Don’t number story cards – tempting, but pointless overhead.  Short title is better.
  • Don’t forget the purpose – to remind you to discuss the feature

Final Thoughts

User stories are a TOOL.  They are a great tool that every software developer should master.  But like any tool, it can be misused and thus not yield the desired results.  Also, like any tool, it is not appropriate for every job.  Before you try to use this tool, I highly recommend reading some books, reading blogs of those who have had success, and start small.

Books

 

Collecting Requirements

/in /by

Any stakeholder can specify requirements.  Obviously the requests by users and project sponsors carry the most weight, however stakeholders such as developers, system administrators, and quality assurance personnel need to have a say since they usually have the best ability to manage the quality, cost, and time dimensions.

A requirement is usually a textual specification of the form “The system shall…”  But beyond just documenting WHAT the system should do, you should also document WHY the system must conform to the requirement.  This is helpful when developers interpret the requirements.  It is also helpful when trade-offs need to occur between conflicting requirements.

Where possible, it helpful to express requirements in numerical terms, for example, the “The system shall return results to the users within 3 seconds, given a maximum of 100 records per result set and a maximum of 40 simultaneous users.”  A requirement at this level of detail is helpful to developers, project sponsors, quality assurance personnel, database administrators, and system administrators.  In that example, the technical stakeholders have some pretty concrete metrics to work with and the project sponsor has a reasonable way to verify the fulfillment of the requirement.

Warning.  Stakeholders don’t always ask for what they really need.  They make requests.  It is your job to figure out what the real need is.  You should ask yourself, “What is driving this request?”  Requests provide context for needs.  Is there a marketing reason for this request?  Is there business process reason?  Is there a compliance or legal reason?  Is there a political reason?

Warning. Stakeholders quite often express their requirement in terms of features they have previous experience with.  For example, “I would like a system that can handle email attachments”.  In reality, what they want is a way to transfer files from one user to another, but if the only way they have ever done this is via email, they will explain their requirement in the only language they know.  This represents a different form of thinking for the stakeholder.  Instead of expressing WHAT they need, they are expressing HOW it should perform.  Depending on the sophistication of the stakeholder, this may or may not be misleading.  It is your job to translate “feature speak” back into needs, then recommend features that fulfill those needs.

 

Non-Functional Requirements

/in /by

When we talk about requirements, we are almost always talking about functional requirements.  i.e. the features.  Features deal with WHAT the application is supposed to do.  However, there is another classification of requirements called non-functional requirements.  These fall into the following categories:

  • Usability – the human factors such as aesthetics, ease of learning, ease of use, and consistency of the user interface.
  • Reliability – frequency and severity of failure, recoverability, predictability, and accuracy.
  • Performance – transaction rate, speed, availability, accuracy, response time, recovery time, or memory usage.
  • Supportability – testability and maintainability.  This is important to Quality assurance personnel and system administrators.

NOTE: The actual categorization is not important when documenting non-functional requirements.  For example, there is not much use in debating whether a requirement is a reliability or performance requirement.  The list simply exists as a mental check list of perspectives to keep in mind when looking for requirements.

Unfortunately, these non-functional requirements are rarely considered in estimates.  Exploring non-functional requirements is just as important as exploring functional requirements and can sometimes affect the cost and effort required by orders of magnitude.  For example, if a server needs to have 99.9% uptime the cost is substantially less than a server that needs to be up 99.999% of the time.  Instead of thousands of dollars per year, you may need to be spending hundreds of thousands of dollars per year.

Here are some examples of non-functional requirements

  • System must support up to 100,000 total users
  • System must support up to 1,000 simultaneous users
  • System must support up to 1,000 tasks per user (100 million total tasks)
  • System must support up to 100 projects per user
  • System must support up to 1,000 tasks per project
  • System must be accessible on desktop and mobile devices
  • System must be understandable and usable by users without any documentation or training
  • System must respond to user requests in 2 seconds or less
  • System must be hosted on Rackspace (production)
  • System must run on exactly one VM (to reduce operations costs)
  • System must work on 90% of all browsers used in the U.S.
  • System must be up 99.9% of the time (normal operation and maintenance)
  • System must support disaster recovery of no more than 1 day of downtime
  • System must be easily supported.  No more than 1 FTE support personnel
  • System must be easily maintainable.  Respond to most feature requests in less than 1 week and bug fixes in less than 2 days.

Validating Matching Text using an Angular Directive

/in , /by

This is a nice angular directive I found which can be used with AngularJS validation to make sure the text in two inputs match. The most common scenario for this would be for a form where a user must create a new password.

The directive:

.directive('compareText', [function () {
        return {
            require: 'ngModel',
            link: function (scope, elem, attrs, ctrl) {
                var firstTextBox = '#' + attrs.compareText;
                elem.add(firstTextBox).on('keyup', function () {
                    scope.$apply(function () {
                        var v = elem.val() === $(firstTextBox).val();
                        ctrl.$setValidity('textMatch', v);
                    });
                });
            }
        }
    }])

Implementation:

<form name="myForm">
   <input id="pw1" type="password" placeholder="* Password" name="password1" ng-model="model.Password1">
   <input id="pw2" type="password" placeholder="* Repeat Password" name="password2" compare-Text="pw1" ng-model="model.Password2">
   <div ng-show="myForm.password2.$error.textMatch">Must match Password</div>
</form>

 

This is a very simple and reusable directive that makes sure that the text in the inputs match using some jQuery.

Best practice for file upload and import

/in /by

A common feature in applications is the ability for an end user import data from a file.  Generally the best user experience is to allow the user to select a file off their hard drive and upload it to the server for parsing and import into the database.

However, there can sometimes be technical complexity associated with file uploads and that complexity often distracts from the business logic.  We should first work through the business logic of the import before tackling the technical complexities of uploading, storing, parsing, and cleaning up files.

FIRST create a real dumb import screen that just has a text box in a browser.  We can then manually copy and paste into that text box and submit to server for parsing and import.  There are many benefits to doing this first.

  1. Quick to build
  2. Simple to support
  3. Avoid file loading complexity and focus on business process first
  4. Easy to test
  5. Unit test friendly
  6. Great fallback should the more complex solution of file loading ever fail

I am NOT saying don’t build a better user experience.  I am saying build a simple, easily testable feature FIRST that you always keep in your back pocket for a rainy day.

Client and Server Validation using Regular Expressions

/in /by

Here are some of the regular expressions being used in the Youngevity project. These are important to prevent SQL injection attacks. These validation expressions are being used on both the Code First models and the client side Angular validation.

These are a starting point for us to start tweaking until as a team we get these expressions to a point where we are comfortable. Then it would be nice to have these as our standard regular expressions that we use on all projects thus saving us time going forward.

These expressions are using whitelisting which is just simply specifying which characters are allowed as opposed to blacklisting which specifies which characters aren’t allowed. Whitelisting is considered a best practice when writing regular expressions.

Here is an example of how to use a regular expression on a C# model:

[RegularExpression(@"^[0-9a-zA-Z /.@()!#$%^&*?+_-]+$", ErrorMessage = "Please remove invalid characters")]
        public virtual string LastName { get; set; }

Implentation using AngularJS:

<input type="text" ng-model="customerRequest.LastName" name="LastName" placeholder="* Last Name" ng-pattern="/^[0-9a-zA-Z /.@()!#$%^&*?+_-]+$/">
<div ng-show="requestForm.LastName.$error.pattern">Please remove invalid characters</div>

Basic regular expression which can be used for many different fields:

^[0-9a-zA-Z /.@()!#$%^&*?+_-]+$

Regular expression for telephone #s(this is overkill if you are just going to stick the telephone # in the database but when you need to make sure that telephone #s contain a valid 10 or 11 digit North America # it is good to use)

^D?1?D?(d{3})D?D?(d{3})D?(d{4})$

Validating string is a Guid:

^{?[dA-Fa-f]{8}-[dA-Fa-f]{4}-[dA-Fa-f]{4}-[dA-Fa-f]{4}-[dA-Fa-f]{12}}?$

This once again is just a starting point for us to have a library of regular expressions we can quickly grab when needed. For most fields the basic regular expression shown above will work in most cases. For the basic regular expression used above I intentionally did not use shortcuts that allow you to not spell out each special character which is being allowed. I like the fact that you can quickly see what the allowed special characters are without having to lookup the shortcut via google.

AngularJS and Cookies

/in /by

AngularJS has built in support for cookies. A cookie may be added by simply injecting $cookies into your service or controller and creating a cookie by:

$cookies.MyToken = value;

The value can then also be read from the cookies easily by:

var myToken = $cookies.MyToken;

This obviously is a nice feature which abstracts away much of the javascript usually written for creating and reading cookies.

The problem with the current way angular cookies are created is that all cookies by default are set to expire at the end of the browsing session and as of this post there isn’t a way to change that. The problem has been recognized and the creators of angular are working on allowing expiration to be set on cookies in a future update. For the time being we have stopped using $cookies and are using some simple javascript to create cookies but then use angular to read and delete cookies.

Here is some javascript on how to create a new cookie with an expiration of 30 days:

var expirationDate = new Date();
var myValue;

expirationDate.setDate(expirationDate.getDate() + 30);
document.cookie = "MyToken" + "=" + myValue + "; expires=" + expirationDate.toUTCString();

In order to delete an angular cookie simply use:

delete $cookies["MyToken"];