-2

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?

4
  • Sharing your research helps everyone. Tell us what you've tried and why it didn't meet your needs. This demonstrates that you've taken the time to try to help yourself, it saves us from reiterating obvious answers, and most of all it helps you get a more specific and relevant answer. Also see How to Ask
    – gnat
    Mar 18, 2020 at 8:55
  • Does this answer your question? Describing requirements in SRS - use cases? Mar 18, 2020 at 8:55
  • Just partially, since activity diagram weren't mentioned in that question.
    – dcfg
    Mar 18, 2020 at 9:07
  • @dc_Bita98 Well, UML activity diagrams give a detailed view for use cases in terms of the information flow in a system, so I think these can (and should) be part of a SRS. Mar 18, 2020 at 9:30

1 Answer 1

2

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.

2
  • I wasn't aware of ISO/IEC/IEEE 29148. I agree with you about placing activity diagram in the "System overview" section, because in this case it doesn't dig deep into the logic of the software, but it just provide a general understanding of the program. Regarding use-case, in my opinion the level of detail it reaches can tell whether to put it in the "System overview" rather than "Specifications requirements". A use case diagram should be the graphical representation of a requirement, so put it in that section seems fine. But in my particular case I think it fit better in the "System overview".
    – dcfg
    Mar 18, 2020 at 11:59
  • @dc_Bita98 Yeah. I think level of detail and intended audience of that particular diagram is going to be the best guide for exactly where to put it. If it's to someone trying to get general ideas about the system under design, then system overview is better. But if it's more for someone to consume when doing design work, then closer to the requirements is probably better.
    – Thomas Owens
    Mar 18, 2020 at 12:16

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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