A few Guidelines for a Successful Software Project

This article is an attempt to summarize best practices to achieve a successful identification of the customer’s needs in a software project. Based on my experience, this is one of the riskiest parts of the project. Customers have an idea of what they want, but often they have difficulties expressing needs in terms that are intelligible to custom software developers. On the other side, IT experts have a tendency toward being verbose, utilizing too much tech jargon. This article will attempt to help both groups find a common language.

You will discover each step of the project’s early phases: setting up the vocabulary, identifying roles, writing user stories, designing screens and reports, phasing, defining the dream team, setting up the lifecycle, overseeing some tools, and documenting (yes, this too). As a project, my wish is for this article to become a living document, but under control. Versions will be documented (first tip) …

Vocabulary

The customer has his/her own vocabulary and this is the one that takes precedence. It is not up to the customer to define terms, but to the IT team to identify and list them. The final responsibility of the users is to make sure that the vocabulary is accurate.

Example:
Since the beginning of this article, I have already used two terms to identify the customer side (customers and users) and more terms to define the technical team, which will be in charge of the project (custom software developer, IT experts, IT team). This was done on purpose to illustrate how easy it is to introduce confusion. So, from now on, I’ll use customer and supplier.

Identify Roles

One needs to remember that, in the end, the software will be used by human beings. Humans have a tendency to divide into groups: staff, users, admins… In most web applications, you will find at least 2 groups: users and admins.

Example:
If you’re building a website, users will see the news on your website, while admins will write the news.

One danger: too many roles. It is a common mistake to have too many roles. Usually, you assign rights and permissions to the roles. The more rights you have to manage, the more complex your application will be in terms of usability (customer side) and maintenance (supplier side). Keep in mind the evolution of the application.

Example:
If on your website, you want to have an author role, that is in charge of authoring (writing articles), while the admin can author and validate, you are adding a level of complexity. You can then ask such question as “what happens when an admin rejects an article? is the article saved as draft? is the author notified? if so, by which means?”

➡ Tip:
Look at your organization. Do you have a lot of roles? Is your hierarchy pretty flat? Keep it (the model) simple.

Write Short Stories

“Roles” are for taking action. You should be able to summarize those actions in the form of a short, one-sentence story. Ideally, identify each story so you can track them. Just remember KISS as Keep It Simple… and Sweet.

Examples:
AUT1 – An author can write an article.
AUT2 – To access the area where the author can write his article (a.k.a. the back-office), he needs a login and a password.
ADM1 – An administrator can create an account for an author.

Those sentences may seem dull at first, but you need to make sure that you cover a lot of the behaviors your application should have.

The stories should mainly be written by the customer: this is one way he can start describing the features of the application, in other words: the functional specifications.

➡ Tip:
Dear customer, don’t be shy! Things as basic as “I lost my password, please send me a link to reset it” should be on the list. This list should contain a lot of stories.

Design Screens

Example of Wireframe on a Website

Once you have those stories, you can begin to design screens. Screens should ideally be designed by a UX specialist. In any case, screens should be designed as wireframes, with no color and the minimal graphical illustration. Why? When we review this phase, the supplier does not want the customer to be distracted: the supplier wants him to focus on the application, not the level of red in this error message’s RGB code.

On larger applications, or when you combine several screens, I would recommend you draw a complete sketch of the scenarios the users will go through.

As you get more experienced, you will probably start sketching as you write the user stories. This is ok, as long as you keep the validations in sequence (e.g. validating the stories before validating the screens).

➡ Tip:
Make sure you have crossed out all stories before submitting your design for approval. Validation of this part will probably take longer than the previous ones as most people realize they have forgotten something at this step. Make sure the supplier leaves enough time for the customer for validating the screens.

Design Reports

Truly, in a lot of modern web applications, users have a tendency to forget about reports, whether internal, or more importantly, for the customers.

Follow the same idea as for screens: build mockup reports using Word, Excel, or any other office application. If the reports are to be printed, make sure your mockup is several pages long and that it handles page breaks correctly.

➡ Tip:Once more, don’t focus on the design/graphical appearance but instead, ensure that you have used the right labels for fields, titles, etc. If your report embeds calculations, make sure the formulas are explained in a support document.

Phasing

Once you have defined all your stories, scenarios, designs of both reports and screens, you can start phasing. It is a critical part of the process. Every customer wants everything right away. The supplier role as a project manager is to phase those needs in time.

Example:
I remember being hired for a project where the need was described as “we want a customer portal and in-field technicians equipped with mobile devices to collect on-site data” – this was in the pre-iPhone days. After following a similar process, we realized that the needs were different and we delivered a system that made their technicians about 5 times more efficient without using mobile technology.

The Project Team

Having a clear view of the project team is another key element for success: there must be a project manager on the customer side (UPM, User Project Manager) and a project manager on the supplier team who usually has a technical role (TPM, Technical Project Manager).

Their main role is to gather all the information to ensure that when a decision has to be made, the right information is available. The UPM and TPM must meet regularly and keep track of the decisions made during those meetings.

When the project team is more experienced, the UPM can work directly with some of the engineers on the technical team. The goal is to save time on some minor operations. The TPM needs to be aware of and agree to the interactions taking place (not the details).

Example:
The name used in the notification email is spelled wrong, the UPM can directly contact the person in charge to correct it, without requesting a meeting with the technical project manager.

➡ Tip:
Although it is tempting to go quickly using this method, make sure it is understood by all parties and never start a project this way. Don’t skip the ticket/task creation.

Lifecycle

Don’t go for a waterfall life cycle. Software projects can always be split. My preferred terminology for a development cycle is a sprint. My experience on projects really shows that a first cycle of 2 months (about 9 to 10 weeks), followed by a 6-to-7 week cycle is perfectly manageable.

Why? With the delivery of the first sprint, the customer sees that “something” is going on. From that first delivery, it will be possible to modify the second delivery and definitively correct the third to match the needs. This means that within 24 weeks, the customer will have a product matching his or her needs, where a waterfall may take you the same amount of time without the guarantee of whether you are adequately meeting the customer’s needs.

By increasing the delay, both sides also expose them to financial risk.

Example:
On two projects where I worked on the technical side, the customers ran out of cash. By delivering pieces on a regular basis, we were able to make sure that the customers had a working system. They did not have the systems they wanted, but they were happy that the system could help them in their business. In both cases, the project started again after a few months.

Tools

A frequent question is “which tools are you using?” Well, I cannot answer this question as it depends on many factors: the tech-savviness of the customer, the habits of the customer, and most importantly, the goal of the tools.

For me, at this stage of the project, the tools should serve two purposes: communication between all the stakeholders in the projects and safeguarding the project’s assets.

The specifications, which we discussed in the first part of this article, including the mockups, should be written with some kind of collaborative suite like Google Document or Microsoft Word on a shared system like Dropbox, Google Drive, or HubiC. I highly recommend some kind of page-based system, which will ease review over time.

Technical Documentation

This is certainly the Loch Ness monster of IT. Everybody talks about it, but nobody has seen it.

But you may have noticed that we have been constructing quite a bit of documentation here. “What else do you need?” you may ask…

So far we have not touched on the technical specifications. They should—at minimum—contain the description of the data structure. This means the tables and relations for a SQL/relation database and a basic structure for a NoSQL database. JSON I/O should also be documented.

As we have a customer-centric lexicon, we should have a similar lexicon for fields (databases, files, and I/Os).

Add to the mix a simple “how to get started” for the developers. This should be a simple two-to-three page document giving a technical overview and a pointer to where it all starts. It was easy back in the good old days of C and C++ where you could locate a main() somewhere, but now, with the complexity of web applications and their multiple entry points, this document is a must-have.

Lastly, now is a good time to locate the nearest run book to you. The run book is a system administrator guide that should include how to reinstall the application, the location of the backups and source code, the list of users and location of the passwords, how to set up another developer’s workstation, etc. The run book itself deserves a full article. If you do not start the run book as your project starts, it will probably never exist.

It may look a little light in terms of documentation. I agree. However, I’d rather have a small set of documents kept up-to-date, than a huge inconsistent set.

Conclusion

As a customer, you surely have to adapt the project methodology to your needs, but make sure it is clear to all parties. You must define a project team. You must be rigorous. You must answer your supplier in a timely manner. Remember that this article mainly covers the early phases of a development project, without focusing on developing, testing, managing the source code, and many more tasks that take place during development. However, having a good foundation is key.

As a supplier, you have an obligation to educate and coach your customer. Ethic should drive your decisions, more than mid-term profit by technically locking your customer. Your customer will follow you as long as you keep the rigor of the work.

If you know any other tools you would like to share, please feel free to do so in the comments.

If you want to share a few tips, please just add them to the comments. I plan to update this article over time.

And this is only the beginning of a fantastic adventure.

Article started on Feb. 23rd 2015, first version published on Jan. 13th 2016, minor update on May 25th 2016.