Design is missing requirements section

2 posts / 0 new
Last post
Design is missing requirements section

I've noticed that many of our RACD design documents are missing a requirements section that details the important requirements that need to be satisfied by the design.  As a design reviewer, it would be super-helpful to have a clear statement of requirements that I can check the design against. In the future, people working on changes to the design (maybe us, maybe someone else) will need to know what the original requirements were so they can decide whether any of them have changed or not. Section E of our design document template ("design considerations") is supposed to be where this happens, but instead we've been using it to describe the design itself, duplicating some of the info that should be in Section F (the actual design). 

Each of the (many!) sub-sections in Section E is supposed to state what the requirements for that topic are. The template provides a list of topics (sub-section headings) that might be relevant. These sub-sections only need to identify the requirements; they don't have to explain how the design satisfies the requirements: that's done in Section F.  In fact, Section E can be used as a guide/checklist to decide whether Section F has covered all the important requirements or not.

For example, Section E.2.2 is close to identifying end-user environment requirements, but they're stated as design rather than as requirements. Instead of "Developers, staff, and advanced users can access...," how about, "Developers, staff, and advanced users need to access Information Services web interfaces via standard web browsers."  And then, if there are any other specific end-user environment requirements (OSes, administrative applications/tools) or requirements for other kinds of users, add them.

Section E.2.4 shouldn't list the standards used in the design (save that for Section F), it should instead state the standards-compliance requirements (which ones are necessary and why). E.g., "XSEDE's central information services are important in XSEDE's partnerships with X, Y, and Z, which already make heavy use of standard B. Thus, XSEDE central information services must provide an interface compliant with standard B." If there aren't any such requirements, just leave the section out and we won't have to check the design for them or worry about them in the next version of the design. Side note: "SaaS" isn't a standard, it's a software licensing/distribution model.

Section E.2.8: it should identify specific security requirements and where they come from: a use case, an XSEDE policy, a risk register, a security standard XSEDE is trying to follow, legal issues, etc. The current Section E.2.8 states arbitrary requirements (e.g., "must use strong encryption") without explaining where the requirement comes from. This requirement, and the two-factor statement as well, would be more useful if worded like: "XSEDE's operational policy states that all administrative interfaces must require two-factor authentication." Ideally, this would include a reference or link to a specific policy doc, but if one isn't available, at least identifying the source of the requirement is helpful. Then, we could look at Section F and make sure it shows somewhere that two-factor auth for administrative interfaces is actually part of the design.

Section E.2.7 is a place to identify any requirements on the data storage & distribution. The current contents (a simple description of the design) should be somewhere in Section F. Possible examples of data & distribution requirements: "Data in the warehouse must be protected from unauthorized changes. Changes to the data must be audit-able to determine who/how/when each change was made. The data must only be managed via the interfaces specified in the design. All data objects in the warehouse must have an expiration lifetimes and be automatically purged when the lifetime expires. The warehouse must only hold data that originates from another data repository. All data in the warehouse must have an ingest timestamp. Data should be recoverable in the event of a disaster or cyberattack. XSEDE must not make the data in the warehouse available to third parties (e.g., data dump, mass transfer, replication) except as described in the design."

Delivery Effort Stage: 

Hey Lee,

Yes, section E. Design Considerations is the most appropriate place for requirements.

We will move designs to section F and make sure that E is focused on requirements, including pointersto XSEDE operations documents that drive security requirements.

Thanks for the input!


Log in to post comments