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]
Best Answer
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).