How do you describe your solution/system?

Question

I am about to write some standards/guidelines and templates that project managers, developers and business analysts would use. The goal would be to better understand the solution that is or was developed.

One part of this is providing a standard/guideline on documenting the solution. E.g. documenting the piece of software which solves/meets the business-case/user-requirements.

Now, being a programmer myself I can see that it is impossible to dictate and say "each solution must define X using Y and presenting it according to Z.", as X Y Z is not always applicable etc.

However, I know even for my hobby projects I always end up describing my solutions one way or the other, modules/components, source code comments, API, database model, some taxonomy used, a journal-log, xml format etc..

So in order to continue with my work, I would much appreciate if you could share what you document in order to describe your solution (and preferably also how and why) - I know it will vary greatly depending on many things but any general or specific answer is of interest. Thanks.

update It was not clear, but I was not referring to user requirements with X Y Z. I was referring to all the possible types of documentation a system may have. So read it as "impossible to state that each solution must have: list of required frameworks; operational manual for the server software; required master data; matrix of user requirements vs tests; user interface specification. While it makes sense to produce a such limited set of requirements, it is difficult to be clear and precise as what is the most important/relevant is different from project to project.

Also, I asked this quite a while ago and never accepted an answer, sorry for that. Perhaps, since it is an open question, it would be better as a community wiki?

Answer 1

IF this project of yours is going to enjoy any kind of longevity, you may want to start thinking of using some industry aligned methodology. In the end, you will probably spend allot more time and possibly end up with the same end result.

It also depends what level of documentation you are talking about: For Architectural guidance based on the application, take a look at Microsoft Application Architecture Guide 2.0 (Recently released).

If it's lower level than that, start with something like SandCastle and just expand logically on what it produces.

Personally, I like starting with an Interaction diagram, simply showing how all the components of the system interact with one another, then take each component and break it down into classes. Break classes into sequence diagrams, and keep going until you get to method level state charts or however low makes sense for your project.

If it's higher level you need, take a look at my earlier post: Enterprise, Systems and Application Architecture (best Practise)

At the end of the day, as long as it makes logical sense to the people that read it, and it's useful (as opposed to something that you just have to deliver and will never use again) you've done it right.

The bigger problem is often keeping documentation up to date. That will very quickly bring you to the process and procedure creation/improving tasks.