Understanding your client and their goals

At my time at Vodori, I went through phases of developer maturity. I started out relying on my coding chops to get me through my tasks. This was, as you could imagine, very short-sided. I drowned very quickly.

In the example of our largest international client, I was tasked with building a template. Which would include many individual modules like buttons, containers with columns, forms, etc. When I built out the buttons, I did not accommodate for long strings of text. So naturally when this template went to QA, the defect was discovered.

The mistake I made here was that I didn't know how far the internationalization reached within the app. If I would have taken the time to read the admittedly long-winded, but very informative wiki on the client goals, and how we're helping them reach them, I would have known that we need to accommodate for long strings of text everywhere! Whoops.

After making these mistakes early on, I began spending more time on our company wiki reading up on the client history, our dynamic with the client, what they want to achieve, who their customers are, and many more topics. Having this knowledge proved to be very helpful in coming up with solutions to code problems, and building features. It also helped in prioritizing features and bug fixes as I now had an understanding of the weight of different parts of features based on the client's goals.

While it may be annoying or time consuming, make sure to take the time to understand your client and their business. It will give you ground to stand on when proposing solutions, and it will make all processes smoother.

Writing Technical Requirements

Who should write requirements? Everyone!

Some of us developers feel a business analyst, project manager, or tech lead should write technical documentation. I'm here to tell you that it's not explicitly their job! We need to be part of writing them. In fact, the more stakeholders involved with writing requirements, the less chance of things slipping through the cracks in the development cycle.

I found that at Vodori, while the people I worked with were brilliant beyond measure, not all of them were comfortable writing markup requirements related to CSS styling. This resulted in vague requirements that would force a developer to stop their workflow to ask questions. This also led to missing implicit requirements. Again, this is not their fault. We should have all participated in the exercise!

What do good requirements look like?

Take link styling as an example. It's much more than just the color of the link. Here's an example of a complete set of styling requirements for links. These requirements outline context, colors, states, decoration, and nuance.

These requirements are for links inside of body copy. Links within other areas have a different set of requirements.

• The active state should have no text-decoration.
• The active state should be the color: #4196b4.
• The hover state should have an underline.
• The hover state should be the color: #365d9d.
• The visited state should have an underline.
• The visited state should be the color: #5e4d62.
• The text size of links in all states should always be the same size as the paragraph it is contained within.
• All links within paragraphs should open within a new tab unless otherwise noted.
• Links should have the same font-weight as the paragraph: normal.
• On Safari iOS7 and iOS8, the tap state should be removed.
• On Safari iOS7 and iOS8, the visited, and active state should be visible.

We have to write requirements sooner or later

We have to address the requirements for all of these components at some point. I argue that the development cycle goes faster and smoother when we provide requirements in as much detail as possible before development begins, than to piece-meal it on the fly later on. If we spend the time up front writing detailed requirements, it results in:

1. Less bugs
2. Less back and forth between developers and QA analysts
3. Faster development (developers work faster with things spelled out)
4. Less ambiguity around decisions (the requirements are requirements for a reason!)
5. Higher quality output (with the edge cases covered in the requirements, the quality of the code will be higher)

Of course, we can't always capture everything in the requirements. There will always be some degree of improvisation in resolving bugs. However, the more detailed we can be up front, the better off we will be as we progress in the development cycle.