I’ve been programming professionally for 20 years, and there is one elusive document that still escapes me: the scope of work.
I have seen them… just rarely. There have been Bills of Materials wearing the SOW name tag, but open them up, and it’s just a parts list. Usually I gather scraps of information from meetings and phone calls and jot them down in a notes.txt file that lives with the other project documentation. It’s not great but it’s something, and plain text will outlive all of us.
I’ve written previously about the need for proper documentation to program “correctly,” and I stand behind those words. How can we hope to end up in the right place without a map to where we’re going?
I wanted to write this post to lay out a template for what a Control Programming Scope of Work should look like. Mind you, this would be just a small portion of a project’s full scope. I’m limiting my focus to the areas that I know. I also don’t think it’s going to be that hard a document to create.
About
There really should be a section to start off the conversation. What is this scope of work about? Who is the intended audience? What assumptions are being made before we even get into the system description?
You might possibly want to break these answers out into different sections but I don’t think we need to belabor anything yet. Just set the level of expectations.
Workflow
Since the UI is generally how the user will interact with the system, this is going to be the meat of the document. Show how each screen flows into the next. Identify all functions but it’s OK not to dive in deep yet. Just survey everything from 10,000 feet for now.
Automation
What automation is handled by the system? If there are accompanying pages that allow configuration, those should be examined in detail here. Provide a clear description of what triggers automation to happen, what the expected result is, and what fallback might be necessary should something go wrong. There should be no mysterious operation, only delightful conveniences.
Configuration
How is the system configured? Are there any backups that need to be made? What is the process for loading a new configuration?
Change Management
Even after reading through all this documentation, there are still going to be things that are missed or work differently than expected…even though the programming is “correct” and follows the scope of work. How are those changes handled? If making an operational change affects multiple systems, how will those changes be rolled out? Finding and fixing bugs on the first system costs less than applying those fixes across a hundred others you’ve already released to the customer.
Acceptance
It can get ugly when there’s a vague understanding of what needs to be done. Have the customer sign off on this scope of work so you can refer to it later to say that something is programmed correctly. Do you want to leave them with a system they hate? Of course not, but you also can’t get pulled into the quagmire of endless changes that creep beyond the original project scope. Have them understand they’re asking for new work to be added to the original scope, and that incurs additional costs.
Conclusion
Have I ever seen a scope of work that perfectly captured everything? No. But making a best effort to get in front of the design rather than letting the customer figure it out after they see what they don’t like will result in everyone being happier throughout the project. It’s far easier to reword something in a document than it is to throw out half your code and try again.
An Example
I’d like to create an actual example that I can use as a template for new projects. Once I’ve done that and have converted to Markdown, I’ll host it on my developer site. Stay tuned!
Kiel the Coder 