Welcome to diagrammatic notations and software requirements specification writing. This is one course of the secure software requirements and specifications specialization. While we have gathered requirements using both artifact and stakeholder driven elicitation, performed analysis. Done some negotiations, some prioritization. Now, we need to actually start writing the document. This document is for prosperity. Different companies and different software life cycles will require different levels of documentation. In the waterfall model, for example, full documentation is needed. There can be no ambiguities, no conflicts. Everything must be measurable and your document is going to end up being about that big. In agile methods, often having sets of use cases is pretty much enough. It depends on what methods you're using and what your company requires. In this course, we're going to go over some of the many methods of writing a requirements document in both textual and graphical form. We're going to start with the text tool. Writing a requirements document is like writing a story overall. Both graphics and text are needed to fully explain the big picture. While graphics appeal to readers, we only really want to include them when they're necessary. When those graphics are going to explain complex topics or they're just things that are graphical in nature. There needs to be a balance between your graphics and your text. To get started though, let's look at what a software requirements specification looks like. Most formal SRS documents or software requirements specification documents begin with an introduction and a general description. These are things that you start to come up with when you are doing your initial elicitation and gathering your domain knowledge. After that, the document outline changes, depending on the type of system that you're creating and the requirements of the life cycle being used or the company requirements. The input of the specification and documentation phase is a bunch of stuff, a bunch of agreed upon statements of many, many different types. These kinds of statements involve general objectives, your system requirements. Environmental assumptions. Domain properties and also concept definitions. The output of the first version of gathering all of this is your requirements document or at least the first phase of your requirements document. It will likely take many iterations to develop a full document. During which time, you're also going to be doing much more elicitation, analysis, negotiation and prioritization. Base lining is the process of transitioning from the SRS that's under development to the one that's reviewed and approved. The structure of the requirements document should make it easy to understand. Easy to retrieve and analyze items. Easy to follow dependency links. Easy to trace items back to rationale and really big deal is to make it easy to make appropriate changes. The requirements document is used by customers, project managers, developers, testing groups, maintenance and support, document writers, training personal, legal staff, subcontractors and potentially many, many more. Each requirements documents statement should be precisely specified in an appropriate specification language. This is to support communication and helps the document to be able to be analyzed by software tools or by humans for validation, and verification. There are a wide range of techniques that can be used for specification and documentation and this range from informal, and totally informal to semi-formal to formal. In this course, we're going to be focusing mostly on the semi-formal. In agile environments, if a document is required, free documentation or a discipline documentation instructional natural language along with some diagrams. Those are often used. In waterfall or spiral models, these usually requite heavily on documentation. There, disciplined documentation along with diagrams is needed. In safety critical systems, formal specifications are generally preferred. Formal specifications are wonderful and that they can be formally evaluated, and not just by humans. In this course though, we're going to focus mostly on the first two sets In free documentation, we write in unconstrained prose in natural language. However, just as ambiguity and confusion arrive as in natural speech, these documents can be easily misunderstood and get really messy if we don't organize. Think about how you and your friends tell stories to each other. You tell the story in different orders. You emphasize some things more than others. You use words freely. You don't really, really think about it. In many of the stories that we tell to ourselves and to our friends, we end up with ambiguity. Ambiguities are just inherent in natural language. Word usage is important in the nouns, the verbs and the adjectives that we used. But additionally, [LAUGH] we also most of us like to use run-on sentences. These are very confusing in a requirements document when a developer is looking at it and trying to figure out what on Earth is actually happening. So let's say, for example, that we write a requirement for a train system where the requirement is that full braking shall be activated by any train that receives an outdated acceleration command or that enters a station block at speed higher than X miles per hour and for which the preceding train is closer than Y yards. Think on this statement. From this, when does the train break? This statement could be read in at least two different ways. First, you could say that full breaking must be activated when an outdated command is received or when the proceeding train is too close. A second way of reading this is that full breaking is only required in the case where the proceeding train is too close. Whatever the right interpretation is if you think back on these statements, taking the wrong one would be bad. If the cases don't overlap and cover all possible cases, it's going to reduce the universal truth. So, we need to be careful. While free documentation feels very comfortable, there are many dangers if you start writing a document in this manner. First, forward references are frequent. Forward references are statements that these are statements that you make that you can't understand until later on. For example, later on, we're going to talk about some better ways to approach requirements. We're going to do that in about five slides. Or if you're reading through a requirements document, we're going to learn about this feature component on page ten. By the way, we're on page three. Now not all forward references are bad, but definitions should come first. Hey, forward reference, we're going to come back to that in just a little bit. Another issue is that in free language, it's hard to localize specific information and there's no guidance for the organization. Because it's so free-form, there's also no room for automated analysis by any means. Automated analysis can be used in more disciplined documents to allow for traceability and maintainability, especially.
