I have been developing software for a little while now, but I find myself being asked more and more to generate UML documentation of the code. Previously, I have worked from this documentation but never had to draw the diagrams myself. To date, I have read two books on UML and while I think I understand the symbolism pretty well, I was wondering if there was any way to get a look at a complete system fully diagramed and documented; just to check. My supervisor at work is also struggling with the most efficient way to draw large-scale or high abstraction level diagrams and I would really appreciate a few examples.
We have a very complex program that we have developed, but the documentation is, frankly, hard to read because none of us really know how to write the stuff. For example, if we were to try to describe the high-level concept of the program (i.e. what it does and how it does it) in one overview style diagram, what method is most appropriate? My supervisor likes to use Sequence diagrams for eveything, but Sequence diagrams represent the operation of a system over time correct? What if we wanted a static-state diagram? I prefer component models, but those do not really include the actual calls that are made from each component to the other, it merely acknowladges the component’s dependancies. Any help? Like I said, above, I think that seeing one project fully documented using all of the different modelling methods might be most helpful.
Most requirements specifications use an overview approach as their target audience is quite wide. Hence, readers will need to understand the overall system context and behaviour. Models that use more text are especially useful although they are not as specific as math-like models. For example, I personally find that use cases and sequence diagrams are easy to follow for a lot of readers. As your documentation becomes more specific and you’re looking more into the architecture of the software, the audience narrows down to those who would work with the software, that is, developers.
Therefore, my recommendation, after reading your scenario, would be to start with the requirements specifications. Document the purpose of your software, its domain context and how it is expected to behave given certain scenarios. A lot of writing will be involved. Then, when it’s clear what the purpose of the software is and what its expected behaviours are, then proceed in documenting the architectural design of the system. There’s no general rule in regards to what models to use but use them to better convey what you are trying to document. Documentation is indeed hard when you want to be unambiguous and clear.
For samples, I would look for software requirements specifications and software design documents, which usually incorporates several UML models to illustration the specifications and design. A lot of IEEE (software) standards I’ve come across also makes use of various UML models to illustrate their standard.
