6 Common Blunders That Cause An IT Project To Fail

Working in the Information Technology field for over 17 years has its advantages. Mostly, the knowledge I've gain from being hired to help an IT project recuperate from failure.  As America struggles to get back on its feet, most companies are working hard not to have a failed project. This is because failed IT projects are very costly in that the company spends money; but gets nothing in return. The following paragraphs list the top six reasons I've seen IT projects fail.

#1. Unfounded Requirements Assumptions

Within IT, we all know requirements are defined by the customer (see my blog article titled: Requirements: Understanding the Customer's Vision ). Requirements may come from taking notes during a meeting with the stakeholder and translating the notes into requirements. Alternatively, requirements may also come from making a list of questions that you ask the stakeholder. You then use the stakeholders' response(s) to define one or more requirements. So, what about assumptions? Even if a Business Analyst or Systems Analyst derives assumptions; the assumptions should also be discussed with the stakeholders. What's not a good practice is adding assumptions to a requirements document; and, distributing the document without discussing the assumptions with the stakeholders. Discussing assumptions with the appropriate stakeholder(s) before adding them to the requirements document is essential. This approach develops trust and shows the stakeholders they are in charge.

To avoid confusion or miscommunication, it's best to make sure all requirements are discussed, especially those derived from assumptions, before they are added to the requirements document.

#2. Making Promises Without Understanding What it Would Take to Keep Those Promises

This is one of the most frustrating problems--especially for those who diligently work hard to ensure all projects they support are successful. Those responsible for negotiating timelines with the customer should always talk to the team about proposed timelines before any promises are made. If short timelines are needed, the best approach is to prioritize requirements. This way requirements can be implemented by priority (understanding that all requirements can't be assigned a "High" priority). Negotiating realistic time-frames is key to successfully completing a project. On the other hand, making promises that include short turnaround times for larges amounts of work isn't a good idea. This usually leads to poor quality work that frustrates the customer and makes the entire IT team look and feel bad.

#3. Using a Role Other Than A Business Analyst/Systems Analyst to Gather Requirements
Requirements gathering is about more than just talking and writing. The Business Analyst/Systems Analyst responsible for defining requirements has learned elicitation techniques to define what the customer needs and wants. In addition, the Analyst has learned Gap Analysis techniques, traceability and other requirements-related techniques. Assuming anyone on the team, including Technical Writers or Developers, can define requirements can lead to costly mistakes. The roles in IT are divided such that each team member brings the specialty needed to accurately accomplish specific activities within the Software Development Life Cycle. When a practice other than an industry best practice is used; unwanted, unexpected results will usually surface.

#4. Releasing Software Without Proper Documentation

Before a new system is released, the proper documentation should be created. Most team members hate writing documentation; but that doesn't minimize the fact that system documentation is crucial. Any new business application should be accompanied by the following:

a. End-User materials - User's guides, getting started guides, quick reference guides and other materials needed to tell the user how to install, setup and use the system is important. (See my blog article titled Technical Writing & Technical Training Materials.)

b. Training Materials - Some systems may be complex enough to require user training. For example, Enterprise Resource Planning Systems (ERPs) should never be implemented without a cohesive plan to provide users with training. Training is important because it ensures users understand how to use the system to do their job. (See my blog article titled Technical Writing & Technical Training Materials.)

3. Re-engineered Business Process Document - If a new business application causes an organization's business process to change; it is imperative to educate the users. For example, to order a magazine users may call the support desk. The Customer Service Rep. do the following:

1. Take the order;
2. Type up a label and invoice; and
3. Send the request to the mailroom to fill the order and mail it out.

But, what if the company installs a new system. With the new system, the customer still calls the support desk. However, instead of typing up the invoice and mailing label; the Customer Service Rep. is now expected to enter the information into the system. The system then creates the invoice and sends a notification to the mailroom. Notice how end-user documentation will tell the Customer Service Rep. how to use the system to place the order. But, also notice how the process has drastically changed. Neither end-user nor training materials typically address the business process changes. This is why a plan should be implemented to document the business process change. The documented process change can be made part of the end-user's training. Or, the relevant documents can be given to employees impacted by the change. This ensures the organization continues to run smoothly with little downtime. It also ensures employees understand how to do their jobs with a new system in place. (See my blog article on Business Process Re-Engineering and Enterprise Architecture, Segment Architecture & Solution Architecture ,)

#5. Hiring a Project Manager Who Doesn't Understand the Project Manager's Role

 The Project Manager (PM) is one of the key people on the project. In addition to managing the project budget, timelines and deliverables; the PM is the key interface between the IT team and the customer. It is important that the PM understand the balance between customer responsibilities and the IT team.

I worked on an important project with a PM who negotiated due dates without establishing "how" the work was to get done. The PM wanted the customer to pick the templates and methodology that would be used to complete the work. With due dates already negotiated, I knew the more time it took to get the project started; the less time we had to complete the work. I knew the longer we "sat back and waited on the customer"; the less likely we were to succeed. Instead of sitting around I put together the templates based on the methodology I thought would be best for the customer's environment. Although I was not the PM; I still did not want to be part of a failed project. I pleaded with the PM to take the templates to the customer and ask the customer to simply review and provide input on what we provided. One meeting between the PM and customer gave us the go-ahead we needed to get started. The customer became enthusiastic because the project began to move forward. Things were getting done and the customer knew exactly what we would deliver and the approach we would use to do the work. As problems arose the PM was stumped. But, each time I used my experience to advise the PM on the best way to tackle the problem to achieve maximum project success.

Not everyone on a project team will have the experience I have. But if the team has a Project Manager who understands the various IT roles, SDLC methodologies, the customer's role and most importantly the Project Manager's role and responsibilities--things should go just fine.

#6. Not Using a Cohesive Methodology to Implement Software

It is not uncommon for a non-IT company to believe IT work can be accomplished without a methodology. The one company I stepped into that did not use an IT methodology to complete IT work experienced failure over and over again prior. The non-IT company hired IT people. But, since the non-IT people didn't know what they were doing; they inadvertedly hired IT people who didn't know what they were doing. So, the non-IT company ended up with an IT Department that had extremely weak IT skills.

Consequently, no one in the company trusted the IT Department. When I interviewed to join the IT team; the IT team assured me everyone (besides the IT Department) was responsible for the project failures. I wanted to discuss the methodology being used to do the work. I was told a methodology had not been adopted. So, the first thing I did was point out that it is impossible to successfully complete a project without using an "established" methodology.

I recommended an approach and created and circulated the templates. I documented the approach using a Visio diagram that everyone could follow and understand. Then I suggested that we try the approach out on a small scope of work, which we did. Everything went smoothly and the project was a success. The company adopted the methodology and greed no IT work would be done without using the agreed upon approach.

In short, never try to complete IT work without using an established methodology. These methodology were established after teams attempted to do work without them.

In Summary

Following is a list of things you can do to keep your IT project on the right track and avoid the blunders that cause projects to fail:

#1. Always have unfounded requirements assumptions approved by the stakeholder before they are stated as requirements.

#2. In IT, always understand what it will take to keep a promise before you make the promise.

#3. Always use a Business Analyst/Systems Analyst to gather and manage requirements.

#4. Always make sure proper documentation has been developed before releasing a new software application.

#5. Always hire a Project Manager who understands the Project Management role in its entirety and has experience successfully filling the role.

#6. Always use a cohesive methodology to implement a software application.

Make Implementing SharePoint Easier Using the 4 Architectures

SharePoint is probably one of the best money-saving content management systems on the market today. More than a few organizations have boasted of saving $400,000 or more. And the money-saving stories come from various industries including city government, retail, federal government and more.

But most organizations only harness about 50% of SharePoint’s capabilities—mainly using Document Management, Records Management, Workflows and Business Intelligence. There are a few, however, who have taken their SharePoint implementation one step further and used it to replace third-party applications. SharePoint  introduces external content types, which make it easy to use SharePoint to add as well as view/update data stored in an external database. Its secure store service provides a way to securely connect to external data. But, a project aimed at taking advantage of all that SharePoint has to offer could easily become massive.

This post discusses the feasibility of using enterprise architecture concepts in conjunction with Microsoft SharePoint Worksheets, technical diagrams and guides to implement SharePoint. This post does not discuss doing away with information published by Microsoft. Instead it presents a way to divide a SharePoint implementation into smaller, manageable pieces so a broader range of requirements can be defined and incorporated into an overall SharePoint Implementation.

Basic Enterprise Architecture

Enterprise Architecture presents the framework necessary to break an organization into manageable pieces.  Most Enterprise Architecture frameworks include a Vision and four architectures (Business Architecture, Data Architecture, Technology Architecture and the Application Architecture).  Several enterprise architecture frameworks recommend dividing the organization into segments.

Segment Architecture

A Segment Architecture approach focuses on analyzing a business function within an organization. The Business, Data, Application and Technology Architectures are completed for the segment—a cycle that is repeated until all segments in the organization are completed. Below is a diagram from the Federal Enterprise Architecture (FEA) Reference Model Document. The diagrams show how the federal government has broken its two support operations (Management of Government Resources and Service for Citizens) into segments.
Enterprise Architecture is often used to implement Enterprise Resource Planning (ERP) systems—making it a feasible option for an enterprise-wide SharePoint implementation.

Business Architecture

Business Architecture focuses on the following key areas:  Business Activities (tasks performed to complete a process), Business Rules, Business Goals, Business Services and the Business Functions used to deliver the Business Services. Some Enterprise Architectures also call for performance metrics so organizations can measure their success toward achieving their business goals.

In general, the Business Architecture provides organizations an opportunity to review current  Business Activities for a business function.The objective is to define how the activities are completed and look for improvement areas that SharePoint provides. There are various artifacts that can be used. For example, FSAM recommends the "As-is Business Process Swim Lane Diagram" to capture how work currently gets done. The "Target Business Process Swim Lane Diagram" to identify how work will get done in the future, which should include activities to be automated by SharePoint workflows.

In addition, the inputs and outputs used by a business function (s) is also captured. Data and documents shared by multiple business functions are captured through data-sharing matrices.  Keep in mind that the enterprise architecture approach used drives the artifacts used to document each architecture. 

The most critical pieces of information captured for a segment's business architecture are the activities, roles and the information shared. A business function defines how it does work and the information it creates or produces.  If an organization uses Business Process Swim Lane Diagrams to capture activities and activity steps, the Target Business Process Swim Lane Diagram should include a swim lane for a SharePoint workflow to capture its role in the process.  Also keep in mind that once the Target Business Process Swim Lane Diagram is completed; the SharePoint Developer still needs to create the Visio diagram to define the steps, actions, branches, etc. for the workflow. Following is a segment artifacts business architecture Target Business Process Swim Lane Diagram for Staff Acquisition.

Note:  An Operational Node Connectivity Description Diagram, which is an enterprise architecture artifact from the DoD Architecture Framework (DODAF), could provide additional insight as needed.

Partial Operational Node Connectivity Description (OV-2) Diagram

Breaking the SharePoint implementation work down into architectures and segments gives organizations the ability to implement more in less time because the focus is on a smaller scope of work. This approach applies industry best practices to ensure the project does not become overwhelming.  When capturing the business architecture, information regarding the roles and who does what provides the information needed to configure SharePoint’s security in addition to outlining high-level workflow behaviors.

Lastly, the Microsoft Office SharePoint 2010 Worksheets used during this architecture include planning for audience and content targeting worksheets related to planning workflows, etc. Additional documents can include the Business Process Operations Report, Operational Node Connectivity Description Diagram, Organizational Chart, etc.

Data Architecture

The Data Architecture focuses on the organization’s data. The inputs and outputs captured using the TO-BE version of the Business Process Operations Report identifies the data, documents and records to be implemented. The rules associated with the process are also captured. As the inputs/outputs were captured, a matrix was also managed so others in the organization could indicate whether or not they used a given input or output.

At this this point there is still additional information that must be considered for the Data Architecture, including designing and implementing the Information Architecture.  As additional business functions are assessed the termsets, terms, content types, etc. will increase based on additional information gathered. There are a number of SharePoint 2010 Worksheets used to capture the information needed to answer the above questions. A few of the considerations include the following:

• What data is shared across two or more groups?
• What document templates and forms must be made available?
• What document libraries are required?
• What document routing rules are needed?
• What global versus local termsets and terms are required?
• What records are we managing and what retention and other policies are needed for the records?
• What content types are used to standardize data collection, document grouping, etc.?
• What documents do we want to rate?
• What audiences are associated with what documents?

These are just a few of the questions that are addressed to complete the Data Architecture.

Technology Architecture

The Technology Architecture is used to define the technology required to implement a customer’s SharePoint implementation. Discussions are held regarding servers, software, backup/recovery, planning import and export servers, upgrade paths for any existing SharePoint instances, etc.  Microsoft has developed a number of technology diagrams that can help with defining the Technology requirements for an organization’s server farm. A number of the technology diagrams are in the “Planning Guide for Sites and Solutions for Microsoft SharePoint Server 2010, Part 1.” Any other worksheets related to configuring or building the infrastructure are used in this architecture.

Application Architecture

The Application Architecture is most concerned with application capability and branding.  Discussions held during this Architecture also include capturing information on the capability that should be built in SharePoint to replace third-party applications or outdated home grown applications. The organization’s objective drives what artifacts are used. For example, the organization may compile a list of software capabilities by system (for organizations with multiple business applications). This makes is easy to spot duplicate capability and even duplicate systems. It can also be used to determine what capability should be rebuilt using SharePoint to operate a more integrated environment.

Other areas reviewed during this architecture include what business service applications will be used as well as the secure stores and external content types required to connect to external data. The Microsoft SharePoint Worksheets used include Plan top-level site collections and sites, plan incoming e-mail and all other worksheets that relate to building or configuring software capability.

Summary

More than a few organizations have boasted of saving $400,000 or more. And the money-saving stories come from organizations in various industries including city government, retail, federal government and more. But most organizations only harness about 50% of SharePoint’s capabilities—mainly using Document Management, Records Management, Workflows and Business Intelligence.

Most likely, many organizations do not use SharePoint to its fullest ability because of its many features and using it to its fullest likely means an overwhelming project that is likely to fail. Organizations can be divided into segments and divide the SharePoint work into architectures (i.e., Business, Data, Technical and Application). Dividing the implementation into smaller pieces gives organizations an opportunity to include more SharePoint functionality and experience a more useful implementation that will save money.

The process begins with the Business Architecture, which would use the selected business architecture templates to capture the business activities and steps along with data and documents being shared.  The next step would be to further define the Data Architecture. Although the Application Architecture is defined before the Technology Architecture; the Technology must be implemented prior to the Application Architecture. In other words, update or add hardware before deploying the applications.

Use SharePoint 2010 Custom Lists to Design & Build Custom Applications

This article discusses SharePoint development, capabilities and the tasks required to use lists and libraries to build a site.

As a SharePoint and .NET Developer, I can attest that designing and developing SharePoint 2010 solutions is different from designing and building .NET solutions. In many ways, it's easier to build .NET business applications because Developers don't have to figure out how to build what a customer wants using an existing framework. On the other hand, basic business applications can be built rapidly with SharePoint 2010. 

When a SharePoint Developer builds a SharePoint list SharePoint creates the add, edit and display forms, a mobile version of the list or library, an all items view (that lets you see all the data added to a list); and, RSS feed capability. Imagine the time it takes to manually code all of that functionality in a .NET application. Time-to-market and reduced costs is one key reason big businesses have deployed SharePoint. (The other reason, of course, is they gain the expertise needed to compete for multimillion dollar federal government contracts.  But that topic is fit for a different article.)

The other benefit SharePoint  brings to the table is the ability to easily implement security. With SharePoint sites, SharePoint Site Administrators add the roles and then add people to the role to grant access to a site. If the security isn't configured properly SharePoint automatically prohibits rather than permits. And, SharePoint supports fine-grained security. This means the Site Administrator can add roles and people directly to SharePoint lists instead of accepting the default list security, which is the list inherits the "site's" roles and users. When fine-grained security is used two people with different permissions can look at the same page and see different content. For example, if one person is in sales and another is in marketing; the sales list can be configured so only sales people see it. The marketing list can be configured so only marketing people see it. There may also be lists, on the same page, that allow both marketing and sales to see the list items.  If you understand how SharePoint security works, it doesn't take very long to figure a site to behave the way a customer wants it to. Security flexibility and secure access is one key reason nearly every branch of the US military has also adopted SharePoint.

But the advantage many .NET Developers see with .NET is they don't have to figure out how to use an existing framework. They can build a web application without any barriers; and I whole heartedly agree with this.

But for SharePoint 2010 Developers who learn out-of-the-box SharePoint Server 2010 features, SharePoint Designer and Visual Studio--the world is theirs (figuratively speaking). Building robust, collaborative web applications can be completed within days or weeks (unless complex, custom functionality is requested).  And, these sites can include spunky workflow functionality that further streamlines a business process through automation. SharePoint Developers can also use SharePoint Server, SharePoint Designer 2010 and Visual Studio 2010 to build custom lists and/or libraries. Or, they can create an .aspx page, using an existing master page, and add webpart zones (which are used to hold lists and libraries). The Developers or users can then drop the desired lists and libraries on the page, which is then ready to be deployed. 

Using SharePoint to Design a Customer List or Library

The following paragraphs discuss the various ways a product ordering system could be designed using SharePoint.  (Note that in the real world SharePoint would be used with Microsoft Commerce Server to build an integrated ordering system. However, I still think the ordering system is a feasible design to use as an example.)

For this example we are going to walk-though designing multiple Products Lists (a Product List for each product category) and a Shopping Cart List. We will have a User role and a Product Administrator role. In our design, the User role can view all products and edit two fields on the Products List. However, the User role cannot create new products. In addition, the User role can create and update items in the Shopping Cart list.

In our design the Products Lists will be built from content types. We are building the Products Lists from content types because we would only need to build the list once. That list is then available to the entire site. This will allow us to rapidly build the Products Lists. The Shopping Cart will be built from a custom list. We will design a reusable workflow and associate it with our Product content type. We will also add a workflow to our Shopping Cart.

Product Content Type

As previously mentioned the Product content type will be used to build multiple Product Lists. Using a content type means the SharePoint Developer only builds a Products List once. 

• To begin, we create a list and give the list a name. For example, the first list is created and called Arts, Crafts & Sewing. 
• Once the list is created we use the List Settings option to enable the ability to use content types. SharePoint automatically adds the list content type and sets it as the default content type. 
• Next we add the Products List content type we created. The Arts, Crafts & Sewing list inherits all of the columns in the Products List Content type. 
• Now we have to set the Products List Content Type as the default content type so we can delete the list content type SharePoint added. 
• Lastly, we can add our Arts, Crafts & Sewing items to the Arts, Crafts & Sewing list. 

We repeat these five steps for each product category. Using content types means we can very quickly create usable lists for all of the product categories. The left menubar displays the name of each list we created. The Administrator can click on a product category, on the left menubar, to add the products. The users can then click on a product category to view the list of items added by the Administrator. The following picture shows the the Baby category selected by a user. 

Notice the Limited View is shown to users because the users can only see the columns needed to identify the items to be purchased. The Administrator uses a different view because the Administrator must add columns the user should not see. For example, the Administrator adds the number in stock column, and the quantity sold (a workflow is used to deduct the quantity sold from the number in stock to keep the number in stock current). The Administrator also adds the restock level column. The system can use this column (and a separate workflow) to automatically reorder a product when number in stock column reaches the number in the restock level column.
 The system design calls for the following site columns to be added to the Product content type: Product Name, Category Name, Product Description, Product Price, Product Size, Product Price, Quantity in Stock, Quantity, Add to Cart (which is a checkbox where checked = yes and unchecked = no) and others, as applicable.

Note that there are many ways to build the same application in SharePoint. For example, instead of using content types we could design the application to use a Product Category list template. To do this a Product Category list is created with all of the relevant columns. The SharePoint Developer saves the Product Category list as a template. Then a list is created for each product category using the template.

Alternatively, the design could use a Category list made from a Category Content Type. The Category content type would have two columns as follows: Category Name and Category Description. The Product Content Type would then have a Category look-up column so the Product Administrator can select a category from the Category list when adding products. A third design option could be to add a Category column (using the Choice option) directly to the Product content type. Then add the categories to the Category column so the Product Administrator can select the desired category when adding new products.

However, in this design a separate list is to be created for each category. SharePoint will create the navigation so the Developer will only have to reorder the items on the left navigation bar so they display alphabetically. The initial number of items that will automatically display in the Product list is 100. The system design can also use a SharePoint List Filter webpart to filter products within a category. In addition, products can be sorted by price. The design could also allow for users to rate each item.

Whenever a SharePoint list is created a Title column is automatically added. This column automatically links to the View Details page, which enables a user to see all of the columns associated with the list. However, we can use SharePoint Designer to create a custom View Details page.  We only add the columns the user should see to the new View Details page. When the user clicks an item under the Title column (which has been renamed to Product Name) the user will see the custom View Details page we created. 

In this example we named our custom View Details page as follows: View Product Details. Whether the user clicks View Product Details option from the shortcut menu; or, clicks the item name under the Product Name column the user will be directed to the View Product Details page. 

We also designed our View Product Details page so all fields of the fields are read-only except the "Quantity" field and the "Add to Cart" checkbox. The User role can update these two fields indicate the quantity of a product to be ordered and add the item to the shopping cart. When the Save is clicked on the Product View Details page, the form checks to see if the Shopping Cart checkbox is checked. If it is and the Quantity field is empty, a message displays telling the user the Quantity field is required. Or, if the user adds a value in the Quantity field; but does not check the Add to Cart checkbox then the "required field" message displays for the Add to Cart checkbox. This ensures the user does not complete one field and not the other. 

 
The Shopping Cart

If no errors are found the updated occurs, which initiates the workflow. The workflow checks the Quantity field only (the form already performed the checks to make sure both the Add to Cart field and Quantity field are both completed). If a value is found the workflow captures the product name, quantity, calculates the price for the items, etc. and inserts a new list item to the Shopping Cart list.  The User role never directly adds items to the Shopping Cart list. Instead the workflow copies a Product, on the user's behalf, to this list.

The Shopping Cart List Workflow

The Shopping Cart List has a Purchase drop-down list. The drop-down list includes two options: Keep in Cart or Discard. When the workflow inserts a new list item, it sets the default value to Keep in Cart. The Shopping Cart list was updated to display the "total" based on the Price of each item (which is driven by the quantity of the items purchased). At anytime the user can select "Discard" and save the update. The update action initiates the workflow, which removes the item from the list. The list is managing the total so that when an item is removed the total is updated. In addition, the Shopping Cart List workflow adds the quantity back to the inventory.

Summary

This article outlines how a developer can use content types to reduce development time. And, it explains how workflows can be used to copy a list item in one list to another list. It also provides an overview to the benefits of using Microsoft Office SharePoint Server for custom development projects.

Value-Driven Agile User Stories & Test Cases

I’ve had an opportunity to use Agile methodologies while working with a large federal agency and a few other organizations. The large federal agency project was most interesting because it was a complex project. One thing I noticed right away was the level of collaboration used. The experience was very different from what I had been accustomed to. The Development team was large, but despite its size everything was well organized. Problems were discussed daily and solved before the next day’s meeting. It was great to get experience in supporting a large project using Agile. But I still was not convinced user stories were better. This is one key reason it has taken some time for me to actually write about them.

After spending years writing use case specifications and software requirements specification, I wasn’t sure user stories where a good idea. But after working with them over time I began to see their value. I wanted to use this blog article to discuss the format I use to write user stories and present some examples, which I hope are useful.

Value-Driven User Stories

User stories do a good job of presenting requirements in a way that is more concise and easier to understand. Over the past couple of years I have focused primarily on writing value-driven user stories. This means I try to make sure every aspect of the user story adds value in defining the software functionality as it pertains to user expectations. I think facilitating a meeting does mean asking questions to help users think and talk about what they want. But I also think the BA or SA has some editing to do to make sure the content is as useful as possible. For example, I could write a user story that says: "A salesperson wants to add an order to meet customers’ needs." I’ve included the role (salesperson). I’ve also included the what (add an order) and the why (meet customers’ needs). However, the “why” can be written to add the same level of value as the “who” and “what”. If I rewrite the user story, it might look like this: “A salesperson wants to add customer orders to track products purchased”. This user story ties orders directly to products purchased.

In this example, we would expect the user story conversations to include discussions not only on customer orders but also products. This is useful because a customer cannot place an order without a list of products or services to order from. 

From a Developer perspective (i.e., Database Developer or Software Developer) writing user stories that are concise and value-driven strengthens the quality of the requirements and, ultimately, the product being built. The following example includes a user story that associates software problems with trouble tickets. Notice in the Notes section taken from the conversations, “problem description” is discussed. Also notice the user story description provides insight to the workload and the business users’ objective for the user story (i.e., “they want the system to help them process new tickets in a timely manner”, which results in alerts being added).

To make user stories easier for Developers to work with, I embed the use case in the user story. In the following user story [employee] is the role, [submit trouble tickets] is the use case or the “what” and [to describe software problems] is the why. This approach helps developers transition into user stories more easily. They always know to look to the middle of the user story to extract the use case. And, they know the role is at the beginning of the story with the why at the end, as applicable. 

 

The above user story is ready for development. It includes the details necessary to convey the functionality required for the Product Owner and Development Team to all agree on what “Done” means. Notice this user story is assigned 8 story points. To add story points, the Development Team used the Fibonacci sequence (1,2,3,5,8,13,21,34,45), which when diagrammed shows an upward curve indicating an increase in complexity as the numbers go up . They gave this user story 8 story points. This story serves as the baseline to assign points to all future user stories. More complex user stories will consistently have a higher number. User stories with the same complexity will be assigned the same number. And, user stories that are less complex will be assigned a lower number.

Test Cases

Test Cases are a great way to confirm user requirements have been met. The following capture shows the test cases associated with the “As an employee I can submit trouble tickets to describe software problems” user story.

Initial Task List

During the Sprint Planning Meeting, the Development Team can identify all of the tasks associated with development. The System Administrator should also document any items he/she must complete for development to commence and move forward. If a Database Developer and/or Data Analyst is part of the project these individuals should also add items to the list. Once the task list is created individuals can volunteer for the work they want to complete or the work can be assigned by a team lead, whichever is applicable.

The Barriers/Action Items List

As the Development Team works to complete the iteration items for a Sprint, problems always arise. One way to manage daily problems is to keep a Barriers/Action Items list. The list should be accessible to everyone at all times. It can be updated during the daily standup as well as throughout the day. If SharePoint is used to manage the Barriers/Action Items list, the Product Owner, Project Manager and team members can all subscribe to alerts to be notified as new items are added. This way if you can solve a problem, you hear about the problem as soon as it is recorded.

Hopefully you will find this information useful and it will shorten your workdays and make your career a bit more brighter.

Technical Writing & Technical Training Materials

Getting Started in IT

Technical Writing and Technical Training are two great jobs. If you are a teacher seeking to move into the Information Technology industry, you may want to check out technical training jobs. These jobs relate to teaching, as discussed later in this article. 

My first IT job was working as a technical writer, a career I held for about five or six years.  While working as a technical writer I wrote technical documents for the following types of companies: telecommunications (such as Nextel), systems integration (which design and build complex applications), network security, software development, etc. Although the types of documents written are the same, the most challenging part was learning the terms associated with each company type. Telecommunications terminology is very different from systems integration terminology. This is because different company types use different types of technology. For example, telecommunications companies support wireless phones and other similar products. On the other hand, systems integration companies implement systems such as enterprise resource planning (ERP) systems used to run an entire company. 

Technical trainer and technical writer jobs are closely related. A technical writer writes the user's guides, quick reference materials, getting started guides, installation guides and other technical materials. Technical trainers, on the other hand, plan and design training programs. They also write the training materials and they often stand up front and teach students. However, online training is becoming more common so not all technical trainers stand in front of a classroom and teach students. 

Technical Training Materials

While working for a systems integration company (BDM International), I had to assist with developing technical training materials as well as end-user documents. The technical training materials I created were as follows:

1)    Slide Presentation. The Slide Presentation teaches end users how to perform a task.

2)    Lab Book. The lab book includes learning objectives for each chapter. It also provides instructions on how to perform tasks associated with data already in the system. Or, it provides instructions on specific data the user is to add and manipulate. Each chapter concludes with a list of Review questions to reinforce the learning objectives.

3)    Facilitator's Guide. The Facilitator's Guide is written for the instructor. It includes the information (that should be conveyed to students) for each slide in the presentation. It also includes the answers to the Review questions. Typically, technical trainings will include time for the instructor to discuss the Review questions and provide the correct answer.

4)    Survey. Surveys are typically created to gather information the company needs to make training decisions. These surveys are usually handed out about 10 minutes before class ends so students have a chance to complete them and leave class on time.

Technical Documents versus Technical Training Materials

The key difference between the user's guide and the training materials is the user's guide provides general instructions while the technical training materials include instructions about one or more specific records. For example, a user's guide might include a topic called "Adding a Customer Record". This topic would include general instructions as follows:

-------------------------------------------------------------------------------------------------------

1. Log in.

2. Select Add from the Main menu. The Add page displays. 

3. Select Customer from the Add page. The Add Customer page displays.

4. Enter the customer's information (including first name, last name, etc.)
Note: Fields preceded by an asterisk are required and must be completed prior to saving the record.

5. Once you have completed all information click the Save button. The record is saved and the Add Customer page closes.

Note: If you click the Save ​button before you have completed all of the required fields, an error message will display. If this happens click the OK button on the error message. The error message will close so you can access the Add Customer page. Red text (required field) displays beside any required fields left blank.

-------------------------------------------------------------------------------------------------------

The lab book (which is comparable to the user’s guide) will have the Adding a Customer Record lesson. However, the lab book will also include the learning objectives. Below is an example.

-------------------------------------------------------------------------------------------------------

In this lesson you will learn the following:

• How to add a customer records
• How to recognize fields that require information
• How to save a record
• How to respond to an error message.

-------------------------------------------------------------------------------------------------------

The instructions in a lab book are written differently from the instructions in a user’s guide. Below is an example of the instructions in a lab book.

-------------------------------------------------------------------------------------------------------

Instructions:  In this lesson you are going to add Mr. Wyatt Johnson as a new customer. Please follow the instructions below to complete this lesson.

1. Log into the demo account using the following credentials:

User Name: Jane Doe   
Password:  P@ssword22

2. Select Add from the Main menu. The Add window displays.

3. Select Customer from the Add window. The Add Customer window displays.

4. Click in the First Name field. Add the following: Wyatt.

5. Leave the Last Name field blank. Notice that this field is preceded by an asterisk. This means this field is required. However, leave this field blank for now. This will give you an opportunity to see the error message and learn how to respond to it.

6. Click in the Address 1 field. Type the following:  2244 Yellow Stone Park Rd.

7. Click in the Address 2 field. Type the following:  Suite 260

8. Click in the City field. Type the following:  Pasadena

9. Click in the State field. Type the following:  California

10. Click in the Zip Code field. Type the following:  91101

11. Click the Save button. An error message displays, "You must complete all required fields".

12. Click the OK button to close the error message. Notice red text (required field) displays beside the Last Name field because it is required.
13. Click in the Last Name field. Add the following:  Johnson

14. Click the Save button. The record is saved and the Add Customer page closes.

CONGRATULATIONS: You have completed the Adding a Customer Record lesson.

-------------------------------------------------------------------------------------------------------

Notice the lab book provide specific log in information and tells users what data to add. When a system is built and it is determined that training will be provided on that system; the technical trainer usually provides the content that must be added (if applicable) so users can use the system for training. Based on the technical trainer’s request, the developer will create a demo account that can be used for training and/or customer demonstrations. Therefore, more planning is required for training materials then for technical documents such as user’s guides.

In short, user's guides provide instructions so users can perform a task using any data the user wants to add or update, search or delete.  Technical training provides more specific direction by telling users what records to add, edit, delete or search.

User's Guides - Technical Writing

I learned how to write a user's guide by looking at various users’ guides for products on the market. To practice developing user’s guides I would go to www.downloads.com to select and download various types of software  (i.e., change request, enterprise resource planning, customer relationship management, help desk, etc.). The more I practiced; the better I got at organizing the topics. Eventually I came up with a standardized outline that I could use for the user's guide. I only deviated from the standard outline when I had to. Using this rhythm made it easier for users to understand how the topics were organized. This made it easier for users to find information. For example, my table of contents would look as follows:

-------------------------------------------------------------------------------------------------------

Table of Contents

Managing Customer Records

• Adding a Customer Record
• Searching for a Customer Record
• Editing a Customer Record
• Deleting a Customer Record

Managing Orders

• Adding an Order
• Associating a Customer Record with an Order
• Associating an Employee Record with an Order
• Searching for an Order
• Searching by Order ID
• Searching by Customer Name
• Searching by Employee Name
• Editing an Order
• Canceling an Order

Managing Employee Records

• Adding an Employee Record
• Searching for an Employee
• Editing an Employee Record
• Deleting an Employee Record

-------------------------------------------------------------------------------

How it All Adds Up

Although technical writer salaries started out paying $75,000 or more (depending on experience), annually salaries have dropped. Now, on the average, technical writers earn around $75,000 - $85,000 (and that amount may further drop in the coming years). Those who earn salaries in the $90,000s have very strong technical skills and a lot of IT experience. Technical training salaries are still pretty competitive paying around $85,000 to $90,000 annually. A technical trainer with years of industry experience could probably earn more. However, people with that level of experience usually start their own technical training company to target government contracts and earn millions for their knowledge and experience.

Requirements: Writing Use Cases

Use Case Overview

A Use Case is a requirement that directly relates to a user's or system's ability to do something. The something a user does may include creating a record, deleting a record, editing a record, searching for a specific  record, logging into a system, generating a specific type of report, exporting a data, etc. Some projects use user scenarios instead of use cases. However, many projects still use use cases because this type of requirement has been around longer and provides clearer direction when creating requirements. Use Cases are typically included in a document called the Use Case Specification.

Use Case Properties

Use Cases also have properties. A property is text that provides specific information about the use case. For example Use Case Name and Use Case Description are both properties, Following is a list of the Use Case Properties:

ID:  The identify of the use case. Each use case has a unique identifier such as 1, 2, 3, 4, or 1.0, 1.1, 2.0, etc.

Name:  A unique name for the use case. Examples: Add a Customer Record, Update a Customer Record, Mark a Customer Record as Inactive (which is associated with the update task), Search Customer Records, Filter Customer records, Generate a Customer Orders Report.

Description:  This field provides additional information about the use case.

Date: The date the use case was created or updated.

Actor(s): The user group that will be able to perform this use case. For example, user groups can be HR secretaries, HR Benefits Managements, Accounts Receivable Clerks, Desktop Publishers, teachers, principals, students, parents, etc.

Pre-condition: The condition the system is in before the use case is executed. For example the system might be in a "Validated" state if it is about to store data; but was required to validate the data first.

Post-condition: The condition the system is in after the use case has been executed. For example, if the system just filled an order it might be in the "order filled" state.

Normal Flow: This property outlines the steps the user executes to complete the task defined by the use case. For example, Create a Customer Record the user my 1. Log into the system; 2. Select Customer Management (from the menu); 3. Select Create Customer from the Customer Management page; 4. Enter customer information; 5. Click Save to save the record and return to the Customer Management page.

Alternate Flow: This property outlines any alternate paths a user might take to execute the use case. For example, users might perform step 1 from the normal flow. Then for step 2 users may right click and select Import to import a customer record.  Since users are performing a step differently, this is known as a branch. A branch is used whenever users perform the same task (in this case, Create a Customer Record) differently. Step 3 then says "return to step 5. Normal flow". So the alternate flow only outlines were steps differ from the normal flow.

Includes: This property outlines the Use cases this use case includes or uses. To execute the Create a Customer Record use case users must first  "Log into the system," which is also a use case that defines logging in requirements. Whenever users must perform the steps in another use case to complete the current use case; the current use cases uses or includes another use case.

Extends: When a use case extends another use case the extending use case adds additional functionality to  the base use case. For example, a toy manufacturer may have a program where customers (who meet a certain criteria) can use points they've earned to buy beta toys. Ordering beta toys requires different functionality from the functionality required to order regular toys. For example, customers cannot use money or credit cards to buy beta toys--making the payment method different. Customers cannot purchase beta toys from the regular product stock--making the location where toys are stocked different. In addition customers can't backorder or pre-order beta toys. And, customers must meet a certain criteria  to view the available beta toys. Therefore, there should be a use case that supports the functionality to "Place an Order". The "Order Beta Toys" use case would extend the "Place an Order" use case.

Business Rule(s): Many companies establish business rules. Some business rules must be enforced by a system; while other business rules cannot be enforced by a system. If a business rule is to be implemented or enforced by a system; it is associated with the applicable use case.  Examples of Business Rules are as follows: 1. An employee must work for the company for 3 years before he/she can enter a customer order into the system. 2. A Customer Service Manager must approve the order before the products are shipped. (Note that both of these business rules can be implemented by the system.)

Feature(s): The feature is the highest level of requirement. Features are used to group a use case. Examples of features include Generate Reports, Manage Customer Records, Interface With Accounting System, etc.

The Use Case Specification

Use Cases are typically added to a Use Case Specification. The Use Case Specification is a document that includes the use cases along with the property details for each use case. Once the Use Case Specification is completed; it is distributed to the users or user representatives for review and feedback.

Requirements: Understanding the Customer's Vision

Establishing the Vision

One of the most important aspects of designing a system is requirements gathering. A company can have the most seasoned user experience professionals, top-notch developers and exceptional testers that catch every defect. But, will the customer be happy with a beautifully built, flawless product that isn't what was needed? Probably not!

For over 8 years I've worked as a business systems analyst; typically hired as a consultant after a project has failed. And, in most cases, the projects that failed did so because incorrect assumptions were made. And, requirements were then written from a mixture of inaccurate assumptions and customer statements.

The only way to accurately identify customer requirements is to ask questions. Ask questions and let the customer state his/her vision for the implementation. Be sure to ask about business problems and needs that may have initiated the need for the project. You can manage this information by creating a list of business problems and/or needs. Ultimately, all requirements and problems/needs should be managed using a requirements management system such as RequisitePro.

 

Problem/Needs List

1.1 NEED:  Need a dashboard that reflects current sales by region

 

1.2 PROBLEM: Currently, end users are not able to associate a customer order with a region (data can only be associated with a city and state). Should we have the system assign the region based on the city/state? How can we fix this problem?
1.3 NEED:  Need to be able to generate reports for segment marketing. We need to implement a business intelligence solution.
1.4 PROBLEM: All employees can add order records, when only Customer Support should be able to add order records. What’s the best way to address this problem?

 

Notice, with each problem the customer realizes that it’s a problem; but the need that will be used to fix the problem has not been identified. Ultimately, all problems should be translatable to a definite need that everyone agrees on. Following is the updated Problems/Needs list with the problems translated to a need. (Note that with requirements it is good to keep all of the information in place and add notes as changes are made. Then as questions arise as to where the requirement came from, you have the historical data to refer to.)

Problem/Needs List UPDATED

1.1 NEED:  Need a dashboard that reflects current sales by region
1.2 NEED:  Add region data added to the database.  Need to get the CD from the Post Office that includes city, states and zip codes. Verify that the region data is also included. If not our DBAs will need to add the region data.  (Description for the need is: This need resolves 1.2 Problem:  Currently, end users are not able to associate a customer order with a region (data can only be associated with a city and state). Should we have the system assign the region based on the city/state? How can we fix this problem?)
1.3 NEED:   Need to be able to generate reports for segment marketing. We need to implement a business intelligence solution.
1.4 NEED:   Need a Customer Support Role. This role should be the only role with the right to add a customer order. No other roles should be granted this right. .  (Description for the need is: This need resolves 1.4 Problem: All employees can add order records, when only Customer Support should be able to add order records. What’s the best way to address this problem?)

 

Once the problems/needs list has been completed you will need to ask about the Features the system is to support. Features are the highest level of requirements.  The features will ultimately be used to organize the use cases.

Following is a list of features to provide an example of what a feature might look like:

 

Produce Features

 

1.     Manage Customer Records

2.     Interface with the XYZ Accounting System

3.     Generate Business Intelligence Reports

4.     Manage Sales Records

5.     Manage Employee Records

6.     Manage Customer Orders

 

Both the Problems/Needs list and the Product Features are added to the Vision document, which includes other information such as information about the stakeholders (individuals who are directly impacted by the success or failure of the projects). The Analyst should ask stakeholders whether or not they have any type of success criteria. A success criterion is a requirement that the system or project must meet for the project to be viewed as a success. For example, a success criterion may be that the system must be in place by a specific date. If this is the case adding a priority to your features, use cases and functional requirements become critical. When you have short timelines, you will need to work with the stakeholders to prioritize the requirements. Requirements marked with a “High” priority are implemented first. Then the “Medium” priority requirements are implemented once all “High” requirements have been successfully implemented. Lastly, your “Low” priority requirements are implemented once the Medium priority requirements have been implemented.  The following table shows an example of the High, Medium and Low priorities mapped to features, use cases and functional requirements.

 

 

Features	Feature Ranking = High	Feature Ranking = Medium	Feature Ranking = Low
Use Cases	All Use Cases = High priority	Approximately %50 of use cases = High priority – ONLY IMPLEMENT THE USE CASES MARKED AS HIGH.	Less than %50 of use Cases = High priority– ONLY IMPLEMENT THE USE CASES MARKED AS HIGH
Functional Requirements	All functional requirements = High priority	Approximately %50 of functional requirements = High priority– ONLY IMPLEMENT THE FUNCTIONAL REQUIREMENTS MARKED AS HIGH	Less than %50  of functional requirements = High priority– ONLY IMPLEMENT THE FUNCTIONAL REQUIREMENTS MARKED AS HIGH

 

 

In addition to adding information about the stakeholders, information about the end users of the system is also included in the Vision document. Other information included in the Vision document includes the technical documentation and end-user training requirements as well as a high-level list of other requirements such a performance. Once the features have been identified, the use cases are defined and added to the use case specification.  Then the functional requirements are defined and added to the software requirements specification.

To accurately design a business solution from requirements; the analyst must take on the role of a detective. He or she must search for unknowns; and, turn mysteries into concrete statements for feedback. At times the analyst will have to draw conclusions from provided information; and, clearly state those conclusions for feedback. Thorough investigative work is what it takes to accurately define a business solution. But it also takes an understanding of the technology associated with the project.

It's also good practice to gain an understanding of any initial groundwork already laid for the project. For example, ask for a copy of the Statement of Work (SOW). Also, ask for existing system documents, system diagrams, and access to the current system, if applicable. And, in some cases, personal time may need to be used to read through the materials--if the deadlines are tight. But, it is worth it to put forth the effort to gain this insight prior to meeting with the customer. This allows requirements gathering sessions to be used to gather requirements.

Summary
Below is a list of tips you may find useful while meeting with customers to understand system requirements:

1. Ask for existing system or project documentation.

2. Be willing to use your personal time to learn concepts if deadlines are tight.

3. When meeting with the customer ask questions. And, make sure the stated business problems/needs are addressed.

4. Enter all requirements into a requirements management system.

5. Perform a gap analysis between the current system, the business problems/needs and the use cases and functional requirements. If a business need has not been translated into an actionable requirements be sure to translate it to either a use case or functional requirements—based on the need and how it is to be implemented.

6. Write questions that will help close the identified gaps. Then be sure to obtain complete answers to those questions.

7. Update the requirements as you receive answers to your questions.

8. Generate a trace matrix or report for customers to review.