Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I am trying to prepare my first software design document. I am self-taught and have no formal training in CS. Having done a wee bit of reading up on it beforehand, I have created a list of Requirements, Qualities and Non-Qualities for the system, which provide an overview from a managerial viewpoint on what the project is tasked with providing. The intent was for these to be convertible into design Constraints, which in turn would guide justifiable design decisions. So far they do not get into many specifics of what resources are to be provided, but are general in that they should apply to all resources present in the system.

I am having difficulty, however, in proceeding to the next step. What exactly is a Design Constraint supposed to look like? How specific or general should it be? How do I convert domain Requirements into Constraints? Have I already gone nuts and over-specified things? :-)

Background
I am the only programmer at a small service company. We have a current HTML with PHP PIs application which grew organically and has no test infrastructure. Editing one bit has repercussions and unintended consequences in far flung parts of the app. I want to replace it with a more professionally designed (in fact, any kind of designed) one, object-based with a test suite. Management doesn't know about programming and I need to know which of the current features are cruft, which workflows are bogged down, etc. This is intended to be my guidance both during a perpetually postponed design meeting and during implementation.


So far, I have the following:

Terminology

  • "Owner" refers to a company or division running their own deployment of the Software, with data independent of any other deployments.
  • "Developer" means an individual who is either a programmer with write access to the source code, or a database admin working for an Owner.
  • "User" means an individual who has authenticated access to a deployment.
  • "Staff" means a User who works for an Owner.
  • "Client" refers to a User who is a customer of an Owner.

REQUIREMENTS
What features must the service exhibit?

  • Platforms: Access to the service must be available via a variety of recent-to-modern, general business computing devices. (i.e. desktop, laptop, tablet and smartphones as of 2013).
  • Mobility: Reasonable efforts at providing access to the service for all Users must be made, regardless of their physical location.
  • Secure: All data must require authentication and authorization to access, and non-safe requests must come with sufficient confirmation that they were initiated by user intent.
  • Access Controls: Resources and sets of resources must have variable authorization permissions.
  • Admin Powers: Read and write authorization to individual resources and sets of resources must be seperate.
  • Unbreakable: The system must not be able to be put into a "broken" state by Users.
  • No Clobber: A User should not be allowed to overwrite another user's changes unknowingly.
  • Off-line: A User's scheduled events for the current day must be readable off-line.
  • Rapid Bootstrap: New Staff must be able to get up to speed on the internal side of the system quickly.
  • Owner Agnostic: Nothing specific to one Owner should be present in a new, clean deployment for another Owner.
  • Brandable: An Owner must be able to configure the system to exhibit their branding and corporate specifics.
  • Safe Data: A frequent and reliable back-up of all data must be easily scheduled.

QUALITIES
What other features would we like the end product to exhibit?

  • Fast developer turn-around for bug fixes.
  • Fast prototyping for new features.
  • Error-free implementation of new features.
  • Regression-free changes.
  • Attractive Client UI.
  • Efficient Staff UI.
  • Widest device and OS support reasonably achievable.
  • All accountability/blame data (who did what, when?) should be involatile.
  • All other data should be editable by a user with sufficient authorization, without needing a Developer.
  • Data back-ups should be creatable on demand by a sufficiently authorized user.
  • Data back-ups should be restorable on demand by a sufficiently authorized user.

NON-QUALITIES
What features are not important and will allow flexibility of design?

  • Programming language choice
  • UI monolingualism
  • We do not need a generic resource import or export system.
  • [this list is incomplete]
share|improve this question
    
I would chiesel those requirements down a bit. Last I checked, there are a heck of a lot of "modern general business computing devices" available that you'd have to make sure it works with them all. –  Neil Jun 17 '13 at 14:11
    
Everything you need to know about Design Constraints is probably here: bitslot.info/ch22lev1sec4.html –  Robert Harvey Jun 17 '13 at 14:53
    
@Neil I have clarified it a bit. Basically that is there to say it doesn't need to run on old computers/feature phones, and it can't be limited to just Windows boxes running IE 7 (or whatever). –  Nicholas Jun 17 '13 at 15:12
    
@RobertHarvey Okay, I've read that page. It was very short and I didn't really get what it was saying. It did suggest providing reasons why to each of the requirements was given, so I will add those. –  Nicholas Jun 17 '13 at 15:14
    
I'll be a little clearer: I don't think you can convert a list of requirements into constraints. Constraints are merely a special form of additional requirements. If you read the book page I linked, you already know that one type of constraint is legal constraint: writing your program in a way that doesn't break any laws. Another type of constraint might be hardware specifications: "Application requires a Wintel computer with two gigabytes of memory." –  Robert Harvey Jun 17 '13 at 16:58

3 Answers 3

up vote 1 down vote accepted

As Robert noted in a comment, I really don't think you can fully encompass all your design constraints in one place. Since you mention that you're intending to document your design constraints to assist with your design decisions, I'm assuming you are working in a waterfall-style development environment. See the Criticism section on Wikipedia regarding waterfall development - while waterfall development may be justified in some cases, there's a reason why agile development is catching on. Since you are free to start developing a product in small increments, as soon as you find that something doesn't work, you throw out that piece and then try a different approach. It's also much more reactive to changing requirements over the course of a project.

Waterfall development often wastes lots of administrative time up front - how many of us have had to deal with a requirements document that is many dozens of pages long, only for it to be essentially useless towards the end of the project, since the requirements have changed over the course of its development?

So far, I haven't directly answer your question regarding how to document a design constraint; rather, I'm suggesting that you don't do it all up front. You don't describe what your development environment is like (meaning, if it's in a large company, you're self-employeed, etc.), but if you can change the expectations of what needs to be delivered up front before any development is done, I think that will help you enormously. If I can twist your question into, "What should I document up front?", then I would suggest you look into formulating user stories instead, which should better document the true needs that should be known up front.

(By the way, if you are working on a solo or small team, you would also benefit from reading up on lean development, which emerged from the Agile movement, and further focuses on removing waste from the development process).

Edit, based on Nicholas' comment:

It sounds like you are probably in a tough spot. The above links in my answer cover each of those areas that you're not familiar with (jump to the top of the Criticism link to see the full scoop on Waterfall development - if you're not familiar with Waterfall versus Agile development, it's almost certain you are doing the former).

Do you have a feeling for how flexible your management's expectations are for what a development project entails? If you feel comfortable bringing the idea up to them, I think you would really benefit from a lean technique, though admittedly, without having a person experienced in lean development there to guide you along, you might find it daunting at first.

If, by chance, you have a Pluralsight subscription (or don't mind signing up for the free trial), their course called "Best Practices for Software Startups" covers the principles behind lean development and would give you arguments to bring to your management as to why you shouldn't try to plan all these design constraints right from the start of a project. (Alternatively, there are a number of presentations you can watch on YouTube).

share|improve this answer
    
I don't have a clue what 'waterfall' is, so maybe I have been doing that for years, or maybe not. I am superficially familiar with extreme programming, agile development and user stories, (have read all the funny three column website about it) although I have never used the techniques. I am already trying to get user stories into the dev process but my boss is fighting me ("too many cooks spoil the broth"). I got a telling off yesterday just for asking the other staff, who will actually use the app, to provide me with some. In absence of those, I am doing what I can alone. –  Nicholas Jun 18 '13 at 21:02
    
Okay, so I have now done a little additional reading around waterfalls and lean development, and to me it seems Agile and Lean are still based on Waterfall, just in smaller chunks ("one feature at a time", where feature could be a small class or a few new functions). The Requirements -> Design -> Implementation -> Test steps are still needed, and must be performed in that order. –  Nicholas Jun 20 '13 at 11:04
    
I think that's a fair, abstract observation of Agile. There's of course more nuance to it than just "mini-waterfall development," since you have a stakeholder involved every step of the way, an assumption that you're constantly refining a working product rather than planning out everything from scratch, transparency of the entire process, etc. But thinking of it in terms of little waterfall-like projects isn't too far off the mark. Your last sentence isn't exactly true, though, since testers are often involved from the start to plan out tests before any implementation is actually completed. –  Derek Jun 20 '13 at 16:33
    
And speaking of testing, to make it relevant for you as a solo developer, you can create automatable tests yourself before writing your own implementation - see Test-Driven Development for more on that, though you'll probably want to consider that later on, as I've already encouraged plenty of change for you to think about! –  Derek Jun 20 '13 at 16:59

Narrow it WAY done and use an Agile methodology to do it piece by piece.

Given the situation you describe (basically a mess) and the system you desire (cleaned up) I would recommend you tackle this one small piece at a time.

I would also remove these 'qualities'

  • Fast developer turn-around for bug fixes.
  • Error-free implementation of new features.
  • Regression-free changes.
  • Attractive Client UI.
  • Efficient Staff UI.
  • Widest device and OS support reasonably achievable.

because everyone always want these. It may help to think of the opposite for any requirement you have, as this would show that you don't want Slow developer turnaround, errors, Unattractive client UI, Inefficient UI, etc. As no-one really want any of those things, making them a requirement doesn't help a lot (though they are worthy principles). They are also very general and non-specific. Each one of them begs the question "but what does that actually mean in practice" as the devil's in the details.

I would take the requirements you have listed and focus on them one by 1. You have 12 which is convenient for a 1 year effort with 1 month on each as a primary focus.

The biggest things are too avoid are traps of getting overwhelmed by the volume and of generating too much detail in the planning.

You will also need a great deal of patience as at each step you will encounter difficulties and problems to overcome. In these situations it's often the tortoise that wins.

share|improve this answer

Since this post is tagged as "architecture" I'll weigh in from an architecture perspective.

You're on the right track with respect to the kinds of requirements you are gathering. I would classify what you've shared more generally as architectural drivers. That is, some minimalist set of information that you can use to drive the architecture design. Most folks divide architectural drivers into four buckets.

  • Technical Constraints
  • Business Constraints
  • High-level functional requirements
  • Quality Attributes or quality requirements

See discussion on "How to handle 'ilities' (or non-functional requirements) for a project planning/prioritization/work-allocation?" and "Why bother differentiating between functional and nonfunctional requirements?" for some discussion and background.

Constraints are immovable, absolutely must have decisions made by at least one stakeholder that have significant influence over the design of the architecture. Here is some specific advice with respect to dealing with constraints.

  • Always be very careful about choosing constraints.
  • Avoid to the greatest extent possible artificially constraining the system -- have a good reason for creating a constraint.
  • Design decisions can change. Constraints cannot.
  • Design decisions that you make may become constraint-like due to other influencing factors (time, budget, brittleness, etc.).
  • Requirements are always negotiable, therefore they are never constraints...

It's subtle, but there is a huge difference between a constraint and a design decision. A design decision is something that you, as the architect, chose therefore it is something that you can also change. A constraint can never be changed. This is important because it clearly lays out for the team and architect what you control/influence vs. what is influencing you.

I like to think of constraints as load bearing walls for your system. If you were building a house, the load bearing walls are the ones that absolutely cannot be moved without serious - possibly catastrophic - costs. Deferring major decisions until the last possible moment as advised in other answers is great advice. But the assumptions that you make in the beginning of the project - especially the things that are flexible vs. immovable will haunt you for the entire project.

Some simple examples --

  • Technical Constraint: "Customer says the system must run on Apache/Linux"
  • Business Constraint: "Go-live must be before the November trade show"
  • Design Decision that becomes constraint-like: "We're going to use MongoDb to store the data." You could change your mind later, but this was possibly a significant decision. Frameworks and toolkits often fall into this category.
  • Design Decision: "We're going to use heartbeat to detect server failures"
share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.