Drasil: Design Documentation for Projectile

[smiths]

One of the reasons for creating Projectile was to have a simpler example to help us understand the best approach to design documentation. To help us see what the target documentation, it would be great if you could create an MG and MIS for Projectile. You could follow the example of SWHS (https://github.com/smiths/swhs/tree/master/docs/Design). When you do the documentation, do not be shy about using copy and paste to borrow material from the SRS. This will show us the parts that can be generated from knowledge that we already have.

Once we have this example we can start discussing if this is the kind of documentation we want to generate.

@bmaclach may have some ideas to contribute on this issue.

[samm82]

SWHS has things split up differently than my code (which is based on GlassBR). The input loading, calculations, and verification are all done in the same module in SWHS. Do you have a preference on which way you want the MIS set up? @smiths Eventually, I'm sure this will be a variability.

EDIT: I guess my question is should I change my code to match the MIS, or the MIS to match the code? This will probably easier to answer once we generate the code.

[samm82]

I have some questions about the changes sections:
1) The first section is called "Likely Changes" in the SRS and "Anticipated Changes" in the MG. Should we call it "Likely Changes" everywhere for consistency?
2) In the SRS, the LCs and UCs are two separate sections, and in the MG, the ACs and UCs are subsections under "Anticipated Changes and Likely Changes". Which is desired?
3) In the MG for SWHS, the sections have the intros shown below. How much of this information should be captured in the SRS, and how much should be removed from the MG, if any?

[bmaclach]

@samm82 I seem to remember from past discussion with @smiths that the ACs and UCs in the MG are different from the LCs and UCs in the SRS. In the MG, they are changes related to design, whereas in the SRS, they are changes related to the requirements. So for your question 3, the intros seem specific to design so I expect we will want to keep them in the MG.

[samm82]

Do you think we'd want a similar intro in the SRS?

[bmaclach]

Ah, that may be a good idea. The current intros in the SRS are "This section lists the likely changes to be made to the software." (and similar for unlikely changes). They don't give any insight into why changes are likely or unlikely. I'm in favour of adding more to those intros, though ultimately that's up to @smiths.

[samm82]

Also, I'm assuming the function/variable names in the MIS/MG should match the generated code, @bmaclach?

[bmaclach]

@samm82 Yes, especially for functions that are part of the external interface. Other variable names can technically be different, but I think when we get to generating design documentation the easiest thing to do will be to pull variable names from the same source for both code and document generation, so they will end up being the same.

[smiths]

SWHS has things split up differently than my code (which is based on GlassBR). The input loading, calculations, and verification are all done in the same module in SWHS. Do you have a preference on which way you want the MIS set up? @smiths Eventually, I'm sure this will be a variability.

EDIT: I guess my question is should I change my code to match the MIS, or the MIS to match the code? This will probably easier to answer once we generate the code.

@samm82, I tend to prefer the input parameters storage, reading and verification in the same module. The reason is that reading and verification always happen together. In one way of viewing this, it looks like one module with multiple secrets, but at the right abstraction, it is just one secret. The module knows how to get valid input values. How it gets these valid values can be a secret. Another way to view this, that @JacquesCarette brought up in the past, is as a hierarchy of secrets in the implementation. That is module scan have submodules. Parnas allows this in his decomposition tree, but he assumes only the leaf modules will be implemented.

[smiths]

@samm82, with respect to your questions about the likely and unlikely changes, I do want to keep the text separate. As @bmaclach said, they are different ideas. In the design document the likely changes are related to likely design decision changes. In the SRS the likely changes are related to requirements changes. There is overlap in that the SRS likely changes may be built into the design. This is something we will think about more deeply when we have a more rigorous way of talking about a family of physical models. My guess is that we will have to introduce additional terminology related to variabilties, parameters of variation and binding time. It is premature to lock anything down now.

The same goes for the wording in the SRS for the introductions to the sections on likely and unlikely changes. I agree that the boilerplate text can be improved, but I'd like to make any changes here part of the overall improvements in the template. (SRS 2.0) Let us wait to start modifying the text. We can keep it simple for now.

With respect to variable names, I think the variable names in the MIS should match the SRS, if there is an analogue in the SRS. I have tried versions of the documentation with the code names and it makes it confusing and more work to maintain. We should use the SRS variable names in the MIS, but then have an explicit mapping from the MIS names to code names. This lets us use symbols in the MIS that we won't use in our code (even with unicode). The important task is for the reviewers to be able to verify that the MIS matches SRS. The match to the code can be automated.

[samm82]

@smiths How should the mapping from MIS symbols to code symbols be done? Should there be a table in the Notation section, with an intro sentence being something like "The following is a mapping of the symbols used in the SRS to those used in the code. The SRS symbols will be used in the MIS."

[samm82]

@smiths And should the SRS symbols be used when defining function names or not? (func_d_offset or func_d_offset)

[smiths]

Great question @samm82. No, I don't think you should use the SRS symbols in the function names. The function names are a programming concept, not an SRS concept. It would be neat to use symbols in the function names, but I think it would be ultimately more confusing than helpful. 😄