SSP : Looking at MG documentation

[niazim3]

(Issue #27 )

• [x] not a complete sentence so is awkward to read; perhaps add in "and" and remove the comma present between SRS and MG mentions? (https://github.com/smiths/caseStudies/blob/0f4f403445fab607ae5b6d767fc19dd271a45a7f/CaseStudies/ssp/Documentation%20Files/MG_SSP.tex#L109-L111)
• [x] is SC referring to system configuration? is this contraction popular enough to not be stated as "system configuration (SC)" somewhere? (https://github.com/smiths/caseStudies/blob/0f4f403445fab607ae5b6d767fc19dd271a45a7f/CaseStudies/ssp/Documentation%20Files/MG_SSP.tex#L97)
• [x] although obvious, should it be stated that "Anticipated changes are numbered by AC followed by a number.", similar to the note in the AC description for consistency? (https://github.com/smiths/caseStudies/blob/0f4f403445fab607ae5b6d767fc19dd271a45a7f/CaseStudies/ssp/Documentation%20Files/MG_SSP.tex#L157-L158) (elaborated below)

[samm82]

@niazim3 The original intent of the first sentence is: "After completing the first stage of the design, which is the Software Requirements Specification (SRS), the Module Guide (MG) is then developed." - This could be the update.

[smiths]

@niazim3, the sentence you highlighted is awkward. I suggest you change it to: "In a rational design process~\citep{ParnasEtAl1984}, the Module Guide (MG) is developed after completing the Software Requirements Specification (SRS). Please go ahead and make the change in the case study. Since the MG is not currently part of the generated (Drasil) documentation, we do not need to worry about propagating this change.

SC stands for Scientific Computing. This acronym should definitely be in the MG on the first occurrence. Please add it. Is there a table of acronyms in the MG? We should probably add that too. If we ever generate this document the table of acronyms would be a trivial thing to generate using the information we already have for the SRS.

I do not understand your comment about the ACs. Your proposed change seems to match the original text?

Although it at first seems easier to summarize these issues as a checklist together in one list, it does make it more difficult to discuss each one separately. I know we don't want to create too many issues, but in the future, it is probably easier if you split separate issues so that they can be discussed separately.

[niazim3]

I realize the comment about the ACs was not nearly as descriptive as it should've been; what it's referring to is how the "Anticipated Changes" section has the following sentence:

, but anywhere else lists like the one in that section are made (i.e. in "Module Hierarchy" and "Unlikely Changes") , such a statement does not appear. Should they be added to the "Module Hierarchy" and "Unlikely Changes" sections or should it be removed from the "Anticipated Changes" section since a table of abbreviations has been entered and it is quite obvious anyway? It may not be that significant of a change, but was asking in terms of creating a consistently structured document.

Also, I'll keep that in mind the next time an issue is created, as it does make it difficult.

[smiths]

Now I understand. Yes, please change the module guide to include text similar to how ACs are defined for the other cases where a similar naming convention is used. Specifically, text should be added to introduce the unlikely changes and the module hierarchy.

You are correct that the naming convention is fairly obvious, and given in the table of abbreviations, but it is standard practice to not rely on a table of abbreviations. Good writing rules say that the author should also define the abbreviations on their first occurrence.

Although we are not currently working on the module guide, text for defining the naming conventions for anticipated changes, unlikely changes etc, should be something that we eventually automatically generate. When this is the case, we will not need to worry about the maintenance problem of including the same information in two different places.

Can you also please make the same change in the module guides for the other case studies, since I am sure that this omission is made in all of the examples. If you would prefer, you can create an issue for the other case studies and assign it to the individual in charge of that example.