Documentation question

Call Me Jimmy

Hi.

I'm doing my first proper documentation for a project (functional spec) and there are two areas I'm a bit ambiguous about - System Architecture and High-Level Design.

Now I've read a bit about the differences between the two so I have a good idea of what's what but it'd help to get some more info.

For example, as I understand it the System Architecture should show the distribution of functions (functional requirement paths?) across components of the system, among other things. What would be the best, standard way to convey this information? I was thinking of taking the functional requirements and a UML of the main system components and draw coloured paths tracing where each functional requirement uses system components but it could be messy and noisy.

Another option is to present the diagram of the system components and simply explain how each functional requirement will then use each component (which additionally will help to justify each component).

As you can see I'm a bit unsure. High-level design as I understand it would be more of a complete layman/customer friendly outline of the system with interactions between the system and it's outside environment being a focus.

If anyone can provide any info on any points here I'd appreciate it, thanks!

themink

I would say they are similar terms & probably mean slightly different things to different people. A lot depends on the nature of the system & who the audience for the documentation is. To me architecture would be quite high level showing components & maybe technologies used. The level detail in the architecture varies depending on its perceived usefulness. High level design to me would then be a bit of a more granular look at all or a subset of the overall architecture.

My suggestion would be just do what you think makes sense and helps you describe & summarize the system and the components to yourself. Dont get too caught up in the what specific diagrams you think you 'should' be doing.

Example for me might be an architecture diagram might show a few simple blocks to illustrate the main components in a system: e.g. client, server, database. Some arrows showing the type of information or maybe the protocol used to pass information between them. A high-level design diagram might then show e.g. some of the classes involved in some or all of the components in the architecture diagram

Hope that helps a bit

DublinWriter

High-Level Design = What it does
System Architecture = How it does it