Documenting program architecture

Question

What have people found to be effective methods of documenting the architecture of a large project so that programmers new to the code can "get their bearings" (relatively) quickly?

Answer 1

My favorite type of documentations is drawings. Just figures that explains how all the "stuff" are connected to each other.

In my opinion it is not so important to follow specified standards when you make these drawings, that just complicates things and results in fewer figures being made. And by having a huge standard, you just adds way to much different things you have to understand to understand the drawings. If you can't explain your system just by using boxes and arrows (combined with available developers which can answer questions, of course), your system is to complicated... (this is of course an over-simplification, but in general I think it applies).

Some simple drawings will of course not help if the code-base is shitty. The worse your code is, the more documentation you will need.

Answer 2

Keep a file that describes the layout of the filesystem, ie LAYOUT. This would have relevant path info, where config files are kept, etc. Have a README that describes the projects little deployment instructions and quirks.

Keep both of these files under version control and keep both of the files updated.

From there on the next important thing would be to keep clean code that is easy to read. Comment where necessary, but avoid irrelevant, redundant comments. Refactor, refactor, refactor, until everything is easy to understand.

That would keep me happy coming into a new project.

EDIT: Visio drawings are great, but without a nice readme and text document outlaying what exactly is to be done I don't find them terribly helpful.

Answer 3

Fire up visio and start drawing. When it comes to architecture, I find that diagrams are a great way to get a high level feel for how all the components fit together.

Obviously a diagram isn't enough, so once I have the diagram which shows how all the parts fit together, I then like to document each component in detail.

The main things I'll note are:

• The couplings (what depends on this part and what it depends on) the purpose of the component
• The purpose of the component
• The underlying technology
• The key reasons for choosing to implement the componet in the way it has been implemented

There are other things you can talk about but those are the main ones

Answer 4

Visio drawings and a big Word document. Also I comment the critical (base class) code files with the motivation of the implementation.

Answer 5

I usually find architecture to be in some sort of heavy flux at the start of development, so documenting it at the start is not really a good idea (this is the point of contention against Big Upfront Design). Unfortunately that doesn't make the need for documentation go away. :P

In .NET (Visual Studio, specifically) these are the things that I found useful in documenting architectures and APIs:

• Visual Studio Class Designer for diagrams
• SandCastle + XML Documentation Comments for API Documentation

Answer 6

I gave up on proprietary expensive tools (i.e. visio). I just don't see the return on investment (not the cost of the tool, the overhead and time consumed).

What fails almost always is that the documentation is obsolete before the first day of coding goes by. My solution: Strong Wiki push.

Everyone are responsible and able to update the wiki at any time, images can be made with whatever software they want, as long as at the end there is an image embeded in teh wiki page. This works great for me. I document Database this way as well, Store procedures, FAQ, errors, reports....

Answer 7

I think there's probably a place for some kind of document that explains the philosophy of the architecture. If that makes sense.

In a large application -- do we still say "system", btw, or is that considered a 20th century term -- one would hope there would be a degree of architectural consistency that could be explained.

I'd look to explain the key domain factors that informed the architectural decisions, the options considered and rejected (and why) and then explore the most important aspects of the chosen approach. Something that can be read and comprehended in, say, an hour. 10-12 sides?

If the development has been at all successful, it should be apparent from examining code thereafter where it fits in the overall scheme of things.

What documentation there is (and I become more and more sceptical as to its value as the years go by) should restrict itself to "what" and "why". "How" belongs to the code.