UML use case and activity diagrams in SRS document

Question

I'm writing a Software Requirements Specification (SRS) document compliant with the standard IEEE-830-1998. I've also drawn a couple of UML diagrams, specifically a use case and an activity diagram. I wonder whether is correct to insert those diagrams inside the SRS. And, if that is the case, in which section of SRS should I put them between 2 Overall description and 3 Specific requirements?

Answer 1

I'm familiar with but don't have easy access to IEEE 830:1998. I do have access to ISO/IEC/IEEE 29148, which superseded IEEE 830.

From what I can remember about IEEE 830, and from reading ISO/IEC/IEEE 29148, there is nothing that precludes graphical notations in a requirements specification. ISO/IEC/IEEE 29148, in various sections, refers to "graphic representations", "graphical methods", and similar. The use of tables and graphics in a requirements specification is not only not precluded but appears to be encouraged if it leads to clarity.

With regard to placing the diagrams, it depends.

I would suggest placing a use case diagram in the System Overview section. ISO/IEC/IEEE 29148 states that a "graphical overview of the system is strongly recommended" and gives examples of "a context diagram, top-level object diagram, or some other type of diagram that depicts the system and its environment". I would assert that the use case diagram is one of the diagram types that depict the system and its environment with respect to actors and what use cases the system satisfies. This also aligns with the idea of using the use case diagram as a map - by putting the use case diagram early in the document, it can serve as a guide to the information that is captured by further defining those use cases in a textual or tabular format in the Specific Requirements section, providing something like a table of contents to those specific use cases. Alternatively, putting it early in the Product Functions section could also work.

I would place activity diagrams in a few different places. An as-is activity workflow that shows the current process or workflow fits into a business overview or business environment that may be appropriate for a system overview. Taking the as-is process and annotating it with improvements by the software under design could also support the system overview. More detailed activity diagrams for specific functions or use cases supported by the system would likely fit into the operations section.

Something to consider, though, is using IEEE 830 or ISO/IEC/IEEE 29148 as a set of requirements for your requirements documentation and adapting the structure to fit your stakeholders. Personally, I've found these standards to be very useful in identifying what to capture, but the examples of how can be clumsy and awkward for some systems. Making sure that the documentation is useful and valuable to stakeholders is more important than strictly following the structure in a standard.