Drybydesign booklet

My personal notes on the SDLC for modern app development (in book form).


Project maintained by ariugwu Hosted on GitHub Pages — Theme by mattgraham

DRY By Design

A simple approach to writing good software.

Table of Contents

  1. Preface
  2. Assessment Phase
  3. Requirements Gathering
  4. Initial Design
  5. Resource Allocation
  6. Prototype Development
  7. Prototype Demo
  8. Product Development
  9. Internal Testing
  10. Stakeholder Testing
  11. Pilot and UAT
  12. Predeployment
  13. Deployment
  14. Post-Mortem

Preface

DRY (phrase): Don't Repeat Yourself

My idea for this booklet was to take a few mantras and thread them through the SDLC to both deepen my understanding, and explore the things which often derail a project.

The goal of this book is to show how to prevent things like scope creep, technical debt, project creep, misaligned expectations, and the heroics that every out of control project eventually asks of us. If we can do that then we can keep costs of changes and improvements flat. As opposed to the adage that as a system becomes more complex the changes to that system becomes exponentially more expensive. It's the belief of the author that the seeds of a nightmare project can be identified before they take root - every time.

The title of this book is taken from the notion that design repetition is not something that only happens within code. It's the email after the meeting that contains a slightly different explanation of the requirement than was recorded during the meeting. It's the impromptu wire frame created solely for marketing and never shared with the architecture team - and yes, it's the inconsistency of naming conventions between tiers, the lack of code coverage checks, and the lack of a common voice amongst code that all lead to poor traceability within a project.

The key to every bit of code you eventually write will be traceability. That is, your ability to draw a line from a requirement, to a written base case, to a wire frame, to a block of code, to a test case, and eventually to a bug report, feature request, or confidence demo (where you show off how well your efforts align with the expectations and success indicators).

The stretch goal is to say with some confidence -> "If I keep these things in mind I will have a successful software project."

The aphorisms:

The book is also short because it really should be. What I really needed was a cheat sheet for my own personal adoption of a (fairly) generic SDLC.

Perhaps most importantly it's a reminder to me that every time someone throws out a new wonderous buzz word and claims to be able to fix my project management woes that they are offering the how and not the what. (i.e - The best way to run a planning phase, and not whether or not a planning phase should exist). To that end I hope to very clearly define the what.

Lastly I will say that this book is short. It should be a fun read that you can flip through on a flight and is unabashedly full of jargon. Reusable communication tools are just as valuable as reusable code. When I use the acronym "DRY", it really means don't try to explain a concept or idea in a way that redefines, or reinterprets it needlessly.

The Assessment Phase

Can this be done?

All you really hope to get out of this phase or any phase is a definition of it, and an answer to the question Can it be done?

Sometimes all your superiors are going to want is a simple yes or no. Other times thier going to want you to back up your claims with the quotes from past projects which are similar. In your mind there should be two buckets. The Known and Unknown. The subtitle for the Known will be the Trivial Many and the Unknown will be the Vital Few. It's possible and (honestly) likely that some of the Vital Few will turn out to be Trivial, but you don't know that yet.

There's a lot of gut checking here. Most of my pride as a developer comes from this dark art and my years at trying to master it. The more of a project that gets put into the Trivial Many during the assesment the better I feel about my professional growth. That's because that bucket is a mix of portable code, solid design patterns, and razor sharp katas.

The theme from this chapter that will trace throughout this booklet is this: Regardless of what the business process expects from me I will deliver to myself the amount of documentation I need to feel comfortable with my responsibilities.

Requirements Gathering

What needs to be done?

In the assessments phase you likely had a blue sky pitch that you needed to knock out of the park for someone. Great, now you've won the business and it's time to get into the weeds.

CYA: You based your assessment on something, it's time to challenge those assumptions frankly and honestly. If the assumptions where wrong, or have changed then people need to know that it impacts your assessment.

Here are some examples of what documentation should be generated in this phase:

Initial Design

Let me read this back to you.

At the end of the requirements gather you (hopefully) got everyone to sign off on what they wanted. Now you need to sketch that into a system design that works.

Here are some examples of what documentation should be generated in this phase:

Resources

What's this going to cost? Really?

Prototype Development

I need to work out a few things. Gimmie a second.

Every important event in life has a rehersal of some kind Klocs Kill - the amount of code you ships becomes the tax on future development. (TODO: biblio)

Prototype Demo

Is this what you wanted?

The prototype is not the product

You lucky devil. You actually got the time and resources allocated to produce a prototype for a fraction of the cost of the real system. This is great news.

In my experience this is where a project can become a victim of it's own success and/or buried by it's own shortcomings. As a developer the results of either feel eerily similar.

The first case: You nailed it.

Never has the temptation to rush something into production been higher than when everyone is high on that sweet, sweet praise. You feel good about your ability to read minds. The stakeholders feel good about their ability to ask for things. Life is good. Just kidding, it's not. That bus of kool-aid infused business wonderkins you call a conference room is headed for a cliff.

The second case: Nothing is right.

You can feel people sharpening their claws and looking for scape goats. As a team you've spent quite a bit of time defining various aspects of the project. Now it's obvious that after all of that work you don't seem any closer to a consensus and nothing you've been able to produce feels right.

The wrong answer: In either case there's going to be pressured to push full speed into the next phase and just fix/adjust as things come up.

The right answer: If you can come away with polished success indicators, functionality you can trace to business requirements, and a clear understanding of the resources, time, and milestones for your product then you shouldn't move forward.

Internal Testing

Embarrass yourself in front of your peers.

The assumption here is simple. You application does specific things and you want to ensure those things work. However, in the history of my programming career this has never been enough to keep a testing phase properly scoped within a project.

So the motivation here is going to focus on the not so obvious reasons for being diligent about testing and creating a testing culture.

My keeping users responsible for testing post deployment you ensure that the pain point stays visible and shared. Some of my most successful projects have train wrecked after deployment. The reason is that once people are free from the project management restraints the old problematic methods come back with a vengeance. Bugs are sparsely mentioned in email, requests are communicated verbally, and neither is ever tested properly before "chucking it over the wall" to the land of production and crossed fingers.

As always the key word here is traceability. Every test is linked to an action. Every action linked to a requested feature, and every feature is shown on a wireframe or design document.