Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I don't really know the nomenclature regarding these matters, but here is a brief description of what I want. Please let me know if I should substantiate more.

So I have this larger project involving databases, different languages, and interfaces (SQL, R, C, Python, both GUI & CLI). It's growing a little too big to fit into a simple mental construct of what is actually going on. I am interested in making the mother of all charts mapping out the project from a system architecture perspective. Generally speaking I'd like the information to show some meta information of the data rather and where it is produced / consumed. I guess it is close to a flow chart, but as I am no expert in these matters I am asking for help.

Are there any tools for this? Any best practices regarding formatting etc? How about symbols for all the procedures / classes / methods / functions? Please chime in if you have any opinion regarding the matter.

Just to frame a little bit more what I would be interested in:

  • I rather use tools like Latex than Visio
  • I hate large and fancy IDEs, but I adore VIM
  • I would do with static solutions, but I would be interested in automated solutions too (as long as they are not too complicated of course)
share|improve this question
As a small hint: For graph drawing in a "LaTeX-like" way ie., writing code instead of drag 'n drop, take a look at Graphviz – Tader Aug 22 '11 at 12:28
@Tader, that looks very nice. Some of the examples look very similar to what I was thinking. Mille gracias – c00kiemonster Aug 22 '11 at 12:38
Rememver, it is what you leave out of the architecture docs that make them quicker to use then just looking at the code. – Ian Aug 22 '11 at 16:10
based on your conditions of tools id guess you hand weave your clothes also? ;) – Andrew T Finnell Aug 22 '11 at 21:47
@Andrew: Any tool that requires me to reach over to my mouse one time too many immediately gets garbage collected, that clears away a majority of the IDEs 8) – c00kiemonster Aug 23 '11 at 1:01

I am interested in making the mother of all charts mapping out the project from a system architecture perspective.

You aren't going to find such a thing, or at least such a thing that will add any value. The idea behind any architectural diagram is the architectural view that it provides. When I took my course in software architecture, the focus was on the 4+1 Architectural View Model, but there are other view models as well.

The idea behind the view models is that different people will need different information to do their jobs and make informed decisions. They each need to see a different aspect of the system, and don't want to have to wade through useless information. This means that you'll end up with several architectural models of the system.

Are there any tools for this? Any best practices regarding formatting etc? How about symbols for all the procedures / classes / methods / functions?

Conventionally, UML or an architecture description language is used for architectural models of a system. Depending on the needs of the user of the model, other techniques might also be used, such as flow charts, textual descriptions, and other less formalized diagrams.

The important thing to realize, as an architect, is that you need to realize who will be looking at the product and what information they want. Deliver exactly what they need in a format that they expect and can readily use.

share|improve this answer
Good points. It's always tricky choosing which aspects of the system to go into the documentation. I'm in luck here though, very small set of people who're looking at this thing, and we're all pretty much coming in from the same perspective. – c00kiemonster Aug 23 '11 at 0:58
@c00kiemonster What perspective is that? Who is your target audience? What do you hope to gain from this documentation? Based on your comments, I don't think you are going to find anything like what you expect. I would recommend picking up a book on software architecture (I recommend Software Architecture in Practice, I think it's on the second edition). – Thomas Owens Aug 23 '11 at 1:27
I think my approach has two stages. First, the project is large enough not to 'fit' into an average size developer head. For example, what goes into a particular file that gets written there and read here. I prefer glancing at a big chart is quicker than trying to drill down in source code. This part is trivial though, I could just literally draw it in MS Paint or something. Second, as much as I am curious to see whether there are tools for this, I do realized that would up the ante quite a bit. Such tools would have to be configured etc, so in the long run automation could be a net cost. – c00kiemonster Aug 23 '11 at 7:20
My angle regarding the architecture bit is more that I am interested in how (or if perhaps) people describe them graphically, rather than to see how my system architecture fits into the whole bowl of alphabet soup. But to sooth my general appetite for learning I will try to pick up a copy of the book you mention. If anything I might learn what people consider being so special with software architecture ;) – c00kiemonster Aug 23 '11 at 7:25

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

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