3

I've spent six full days so far working on a spec for a web-app component. Apart from personally wanting some task that doesn't involve Word, I'm wondering if there is a point at which I know that the spec I'm working on is finished (but isn't a spec a constant work-in-progress?). I feel that the spec still doesn't explain a good solution for all the requirements I have, so I'm still on it.

Is there any good heuristic or red flag that says I should stop working on a spec?

Note: As opposed to this question and it's answers, I am looking for a completion metric specific to the design, rather than how to decide when code quality is good enough to know that the implementation is complete.

Community
  • 1
Rafael Emshoff
  • 553
  • 4
  • 18
  • 1
    Similar to this question: http://programmers.stackexchange.com/questions/34356/how-do-i-write-a-functional-specification-quickly-and-efficiently, but the answer doesn't mention any time ratio. – Rafael Emshoff Aug 06 '15 at 16:45
  • Related reading (not a duplicate): **[How would you know if you've written readable and easily maintainable code?](http://programmers.stackexchange.com/q/141005/22815)** –  Aug 06 '15 at 16:45
  • possible duplicate of [How to stop gold-plating and just be content to release working developments](http://programmers.stackexchange.com/questions/167752/how-to-stop-gold-plating-and-just-be-content-to-release-working-developments) – gnat Aug 06 '15 at 16:48
  • Is this a personal project or a professional project? What methodology are you employing? If it's for a client, are they expecting a phase-gated approach? I think that with more details about the context of this project, this is an answerable question. – Thomas Owens Aug 06 '15 at 16:50
  • 3
    I am not sure this is a duplicate, the other question deals with code, this is specifically asking about design and specification. The metrics are different. –  Aug 06 '15 at 16:54
  • @Snowman please re-check it: "I can't stop myself gold-plating code (and _documentation_)..." – gnat Aug 06 '15 at 17:34
  • Consider as well as this is dependent on your ideology of choice. Some agile proponents would shun the very concept of a design/implementation spec. – Alex Aug 06 '15 at 19:50
  • @Alex - I would hope not. Agile may not go into as great of detail.It's Working software "over" comprehensive documentation and not we don't need no stinkin' documentation. – JeffO Aug 07 '15 at 00:27
  • @JeffO They would not call it "documentation", they would call it "big design up front". – Alex Aug 07 '15 at 06:14

1 Answers1

5

What you are looking for is traceability.

Whether you use old-school waterfall or more modern iterative approaches, a unit of functionality necessarily follows a simple process:

  1. Define business requirements.
  2. Define functional requirements.
  3. Define technical requirements.
  4. Design the software. <-- You are here
  5. Implement the software.
  6. Test the software.

At each step of the process, you should be able to trace your requirements back and forth between steps.

  • Each functional requirement (the system shall have function X) must be traceable to a business requirement (we need a system to do X). Note that a business requirement is normally high level and spawns many functional requirements.

  • Each design element traces back to a functional requirement. E.g. the form elements on this screen all support functional requirement X. All of the data requirements in this functional or technical requirement are satisfied by this screen or interface.

When you have 100% coverage throughout the whole process, you know your design is functionally complete.

But wait! Can the design be implemented reasonably? The key here is collaboration. This is where design reviews come into play. Get the key players involved: customer, project management, developers, and QA. Can the design be implemented? Can it be tested? Does it really satisfy the requirements? Once the team comes to a consensus, you are likely done with the design.

  • "Once the team comes to a consensus, you are likely done with the design."That sounds like an easily identifiable goal to go by. – Rafael Emshoff Aug 06 '15 at 16:59
  • @RafaelCichocki Consensus is key, but it is not as simple as a bunch of people sitting around a table and nodding their heads. It is important that each team member answers the question "can I do my job with this software artifact?" affirmatively. I.e. "can I test using this" "can I develop using this" etc. –  Aug 06 '15 at 17:00