What are good guidelines for documenting the analysis phase of a project?

Question

I find myself sometimes writing documents which usually consider 2 parts of a project's plan:

1. Requirements
2. Analysis

By analysis, I mean the different possible ways that we could meet our requirements. My analysis usual includes mock-ups of UI or DB schemas or anything related. It also compares the pros and cons of 3 or 4 different alternatives.

I find that my documents usually lack structure and consistency. I'm hoping to get feedback on what guidelines others follow or templates they use.

The documents I write are never very long-winded. We're a small company who isn't obsessed with process and we like to stick to the point. Not quite Agile but close to it.

Answer 1

Any software problem with depth is going to have multiple competing solutions. It's the great thing about our work! When I write analysis documents (or read other peoples docs) I try to include the alternatives that I didn't chose, and why.

I usually try to think up 10 ways to get something done, then try three, and decide on one. Write up the three that were good enough to try.

As for the analysis document template, there are plenty of good resources for boiler-plate document templates. Are you also writing the technical specification? In my docs, the analysis is always a supporting document to the tech spec, which talks about how implementation maps to requirements.

Answer 2

I'm confused - you said you write up a fully detailed analysis when you have 1 or 2 options (in your comment to John) but then you mention (in the question) that you compare the pros and cons of 3-4 alternatives. I'm guessing the pros/cons aren't fully analyzed?

Since you're combining your Requirements and Analysis in the same document, I'll assume that you've got the full use cases in the first section and then you address them in the Analysis section. I would leave those two sections as is and then add a third for "Other Candidate Designs" or something and then just list the reasons why you didn't choose it. This can be very brief and not require the UI design etc. However, if you've already done mockups and THEN realize it won't work, you could probably include them in the doc. A good goal would be to make sure that the focus of your doc is still on the design you're using, but include sections for those curious about the rejected designs.

As for having Structure and Consistency, we've been using the Rational Unified Process documents for Software Architecture (the SAD). Here's the first link to a template I could find: http://www.cs.toronto.edu/~wl/teach/407/2002/rup-sad.html

The idea is that you break down the system into different "views" and document them. This is heavier than your current document, but some of our clients require the extra documentation so we provide it in this format. Using the RUP SAD you could list your rejected designs in the Architectural Goals & Constraints section or in a special section at the end (which is what we usually do).