Project Requirements and You

Tom Chizek
Sep 22 · 7 min read

Introduction

Record
{
Group : value multiple
Entity :
{
Complex data with multiple parts here
}
}
Record
{
Group: same
Entity Type 2
{
Similar but not identical complex data here.
}
}
...
Record
{
Group: same
Entity Type X
{
Similar but not identical complex data here.
}
}

In general terms, the record has an identifier that groups the complex entities of different types, each with a separate record or number of records into groups. The data structure this is to be turned into is a single record per Group with multiple columns for the complex data. So, something that looks more like this call it type 2 data records:

Group:
Entity Type 1
{
Complex data with multiple parts here
}
Entity Type 2
{
}
Entity Type 3
{
}
. . .
Entity type N
{
}

So, fewer records, but each record is more complicated. To make the project more interesting, existing data in the dataset with type 2 records must be maintained. Well, kind of maintained, it can be modified by the incoming type 1 records.

That’s the setup for today’s discussion on the fun with requirements for merging data.

Most important

Many companies right now are in the position of laying off most, if not all, their IT and software departments. In these cases, it will give the managers who are used to having their software team write these documents a level of comfort to have you write the document and work with them to get the requirements defined. You should not expect to be paid for this work. Consider it an investment in ongoing relationships. Remember, the best customer for a freelancer or contract software engineer is the one that comes looking for you.

Moral, write requirements documents, get them signed off on by the customer.

Customers Don’t Know

The moral of this bit, even if you think the requirements are pinned down, they aren’t until you ship the software and get paid.

You aren’t a Mind Reader

On the other hand, I discovered two specific entities never discussed in the incoming data. My guess based on the discussions was that these entities were going to become additional types of entity in the final data structure, probably tacked onto the end. In this case, I was utterly wrong. When I sent my quick email, they told me to ignore records of these types. These were not currently interesting, and it would be another project later if they become relevant.

Moral, don’t try to be a mind reader if there is any question at all ask.

The Right Detail

I am in no way saying you need this level of detail. For my last two projects, I have written about two pages each. Defining what the data input looked like, what transformations I needed to perform, and what the data output is. What specific data storage used was determined by the customer in both cases, but I documented that as well, so we agreed on it. Then we passed the document back and forth between two and four times with tracked changes on, both making changes as needed from phone calls and emails. In the end, the customer sent it back with an email saying that yes, that is what we want you to do — please tell us how much it will cost and how long it will take.

So, don’t write over detailed requirements. Write the things you need and only what you need. In many ways, the level of detail from those conveyor control documents was insane and useless. By the time the project was in progress, some of the “required” items were no longer available. Some variances had to be requested because a “standard” steel from twenty years ago is no longer standard, and you can’t buy brackets made in that steel except via special order at ten times the expected price.

Moral, enough detail but not too much.

Conclusion

Good luck, and have fun.

The Innovation

A place for variety of stories from different backgrounds

Sign up for The Innovation Digest

By The Innovation

Official newsletter of The Innovation Take a look

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Tom Chizek

Written by

Software Engineer by day, Novelist by night

The Innovation

A place for a variety of stories from different backgrounds

Tom Chizek

Written by

Software Engineer by day, Novelist by night

The Innovation

A place for a variety of stories from different backgrounds

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store