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.

Answer 2

Documentation is always the trickiest part of any project. If you want to start afresh, then you might want to check out Domain Driven Design.

Using story templates can be very benificial if you have the correct template.

As a [X]
I want [Y]
so that [Z]

In a similar vein you might want to look at Use Cases

Answer 3

Use words of the current domain. If there is a generally used business domain word, then use the same word consistently in the documentation and code. If there is a generally used programming term (for example well-known design patterns), use it when writing code and documenting the technical details.

To document how the program will work, as part of the user interface design I produce picture sequences (on paper or powerpoint) showing how the users will perform their task with the user interface. That is a common language that everybody will understand, from users to customer to managers to programmers.

Answer 4

Basically there are many ways to do documentation for projects. 2 approaches I've used in the past are 1) Use-Case driven development, and 2) Test driven development. Since i've only used Test driven development once, I'm advising how to use Use-Case driven development.

The key here is to use the UML notation thoroughly. Users, Business Analyst, and Developers speak different languages (obviously) and what you're try to do is make your documentations have meaning. There are 3 basic documents that are key.

1. Business Specifications - This document is produced by the User, without any interference or consultation with the development team. Why? because this document needs capture purely what the user needs. Example, User wants a program to make coffee. Right now User's coffee machine has to be turned on manually. User's brain takes time to run all cylinders in the morning.

2. Software Requirement Specification - This is where the analyst breaks down the User requirements into functional specifications. The analyst creates flows based on user's needs. This is where you start using UML. Start with Use-Cases and Activity diagrams to get a picture of how the system is going to feel. Get other derived specifications like security requirements and other needs like infrastructure constraints.

3. Software Design Description - This is the technical document that the architecture or solution designer produces to design the solution to meet requirements. The architect breaks down the functional specs and translates the flows into technical specs. Each Use-Case can be broken down into Sequence Diagrams and Communication Diagrams. What you can do with these diagrams is start creating the functions for the classes. These diagrams can be used to develop Class Diagrams. State Machines as you may know breaks down Class Diagrams but, I usually don't go that far. You can also document the entire architecture and break down its components in this document using Component Structures. The document can also include the deployment infrastructure that the system is going to be put in.

Using these 3 documents together can help readers better understand how things work in the system. Programmers can understand where the technical specs come from, and how they will eventually need to function. If you can't make a technical spec understandable to programmers in order to make the right functions, might as well tell them how they will ultimately need to function.

To coordinate with teams members from different levels, for example, users, managers, business analyst, solutions architects, and programmers I create a matrix that connects business specs, to functional specs, to technical/design specs. The matrix will also include testing modules that will be coordinated to the elements to be tested. The matrix is really valuable when implementing the V-Model development method.

Matrix Example: "Business Need A" -> "Functional Spec A" and "Functional Spec B" "Functional Spec A" -> "Component A", "Component B", and "Component C" "Component B" -> "Class A" and "Class B"

Of course this always looks better on a spreadsheet.

Answer 5

Very little unfortunately!

However, if your guidelines are for managers and developers, the language you use is just as important as the way you present it. Avoid using buzz words and marketing jargon, (Here's a good list!)

I personally find diagrams and drawings help to reinforce ideas, flow charts of the intended user interaction with your system may help better present what the system is supposed to do. (With in-depth analysis of how the system actually achieves that afterwards of course!)

Answer 6

To extend the outreach of your project, you'd better use domain words for communication. For requirements discovery, prototype tools can be used to build UI rapidly to make sure requirements well understood. In case your purpose is to find the best way for documenting solutions, I think it does have something to do with solution architecture. Also I think IEEE 1471 standard provides a holistic approach for documenting software architecture. Also check out perspectives and viewpoints approach. Of course you can do it with your favorate UML tools.

Answer 7

TOGAF (The Open Group Architecture Framework) defines a "method" of how an architect should define a solution. A part of TOGAF is also involved in defining what input and output should be produced as part of an architectural project.

However, for your question of what documentation you need that shall be shared between various people (BA, Programmers, Testers, Managers etc), you should look at Views and ViewPoints in TOGAF. All these people you mention are your stakeholders and Views and ViewPoints address stakeholder concerns. So, I would encourage you to have a go at Views and ViewPoints.

Answer 8

Perhaps because I've just read it and it's still buzzing around my head, but I think it's worth reading 37signals Getting Real. While it's about starting up a project, the approach to documentation is highly agreeable to me (as a programmer). It's not to everyone's taste, but if others are on board with the approach then it might even make the documentation pleasurable. I found it so.

Answer 9

Here is a list of things that I scrambled down that I think would make sense to have when describing a solution. I made it a wiki so please join in and challenge and add.

1. Data Repositories (Where is data stored? How is it accessed?)
2. Data Format (Which formats are used? Any new introduced? Specification) size grow?
3. Configuration (What can be configured, what is the default)
4. Library/Framework/Package dependencies (vendor,licence,version)
5. Build solution (how acquire all files etc and step by step to build)
6. Modules (Defined scope / why was module introduced)
7. Class/Source-code Documentation (Generated by Doxygen or equivalent)

Also of interest: 1. Security (Which area of the solution is under security, passw/encrypted etc) 2. Data Transfer (What is transfered between disks/network? By which variables do the