7

I'm a self-taught programmer which means I started writing software by sitting down at an IDE and hammering out some code. When my decisions ultimately coded me into a corner I would refactor and rewrite. This was a great learning experience for me but I want better for myself now. I am starting to see the benefit of creating design documents. So far this has been rough sketches of what I want GUI elements to look like and a few flow charts.

A few other things I've been doing:

  • Top-down and Bottom-up design
  • Design Patterns
  • Requirements
  • Trying to understand the needs of my apps
  • Designing classes before implementing them

But what I am having trouble with is putting it all together. Is there a process or method that works well? Is there an approach to writing the document that I can follow? Perhaps a few steps. Are there questions that I can ask myself? The answers to which will be useful in the creation of an outline for my projects and applications.

5

This answer provides a lot of good information. I want to augment it, not compete with it.

Over time, many organizations develop templates for various documents (design, functional spec, test plan, etc). Often they're derived from IEEE standards -- usually, in my experience, they're simplified from IEEE standards, which seem to be designed for large systems. It sounds like you don't have any institutional knowledge to draw on, but if you do have peers, it's worth asking to see some of theirs just for calibration within your own company.

The purposes of a software design document are to:

  • explain what you're going to do (or did, if you're back-filling), and

  • demonstrate that it is a complete solution to the problem you're trying to solve.

To do the latter, you need to actually state what the problem is that you're trying to solve. You might think it's obvious and will be obvious to your peers, but I have seen more than a few design reviews stall right there, when people in the room have different views of the requirements and overall goals.

Once you've stated the problem, you can cast the rest of the discussion in terms of addressing that problem -- we're using this architecture to meet our goals of extensibility, we're making this compromise because of this performance goal, we anticipate redoing this part next year when the new version of a key library is released so we're keeping it isolated in our system, and so on.

My usual outline for software design documents goes like this:

  • Problem statement and key requirements: not the fine-grained, detailed requirements list that (if it exists) should be in a separate document owned by product management, but the key points from that list that affect how you design the software. Aim for a few paragraphs, not pages and pages. Don't just cut/paste them from somewhere; restate your understanding of them, because your understanding informs the design (so if it's wrong, better to catch it now).

  • Functional specification, if not covered in a separate functional specification. This is where you describe externally-visible impacts -- user interface (and/or API), new configuration settings you're adding, performance contracts, etc. If your system is large or complicated, please do this separately and first to avoid rework later when somebody comes back and says "no, I need it to do this instead" or "that user interface is inconsistent with this other part of our system and you need to fix it" or "we already have too many configuration settings; are these ones necessary?".

    If you have a separate functional spec, I find it's useful to include a brief summary in the form of an example. People might need to refer to it when reading the design.

  • The actual design specification: what are you creating, what are you changing, and why? What problems do you need to address (e.g. we need to address this technical debt before we can add this new thing), and what issues might your design introduce (e.g. this design places a higher load on the server; we think it's ok but we might need to do X to mitigate it). What risks does it introduce? The design should be detailed enough that somebody reviewing it could spot architectural or similar problems before you spend time implementing, but not so detailed that you have to write and comment all your code first before you can distill out a design spec.

  • Testing strategy: how will you validate the work? Do you just need to run the regression suite because you're not making external changes, or will you create new functional tests, or what? This isn't a test plan, but thinking early about how you'll demonstrate that your eventual implementation is sound can help identify problems early.

5

I personally like design documents that are short and fat-free.

  • What are you trying to accomplish?
  • What is your main idea and why?
  • Main decisions
  • Main challenges you encountered
  • What will I - as newcomer to your project - find surprising?
  • What are the 3 classes I should look at first?

To get into the mood:

  • Imagine we are sitting and having a beer. You are telling me about your project.
  • Imagine you are giving a one-hour presentation about your project. What would you tell?
  • Imagine I just downloaded your stuff off github. What do I absolutely have to know before I start looking at the code?

Keep it short and remember to update it once things change. Do NOT write a 100 page design doc. Nobody will read it and it will always be out of sync with the code. Do concisely comment every class and function and write your code in a self-evident manner (short functions with clear names, clear names for variables, etc.). Your design documents should be 3-page affairs. Major components can have their own design documents.

  • Would you deviate from this answer for the initial concept stage, before any coding has begun? – AGirlHasNoName Feb 24 at 14:10
  • I usually first start with ideas, drawings, etc. Then comes googling, research and technical experiments, I try out different approaches. (Maybe someone already solved the technical problem I dreaded most. Maybe the database is not the bottleneck after all. Maybe the business logic is so complicated that it is best expressed in a DSL. Whatever.) In this stage I can get away with a unstructured private research journal or a mind map. THEN the code & the design doc evolve together. – manduca Feb 24 at 15:09
  • BTW, you are doing great! Refactoring once the design is no longer optimal is EXACTLY what I recommend. I do not recommend the old "waterfall" model of first making a plan and the following it to the letter. – manduca Feb 24 at 15:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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