Editorial issues in Projectile SRS

[muralidn]

Impact: Minor

Artifact: Projectile_STS.pdf (https://jacquescarette.github.io/Drasil/examples/Projectile/srs/Projectile_SRS.pdf)

Description

1. The text on pages 25-28 exceeds the page width.
2. The document utilizes hyperlinks to cross-reference Tables, Figures, Sections, etc. For example, Fig:Launch, Section: Instance Models. They do not match the names of the tables or figures. This naming convention may be inconvenient when reading from a hard-copy of the document. Suggest including the index numbers of the relevant item, for example, FIgure 1: Launch.
3. The Physical Systems, PS1, PS2, and PS3 are not marked in Figure1.
4. Section, 3.1.3, and 3.2.1 contain the first mention of Refnames in the document. For example, targetHit in section 3.1.3 is later referenced as GS: targetHit. This deviates from the format used for the definitions of Refnames in the rest for the document

[smiths]

@muralidn, in the future, please create a separate issue for each point. That allows better discussion and tracking of the issue.

The issue with the wrapped text is also noted in #1877. A solution, using short mnemonics, instead of the full names, is given in #1539. When that issue is closed, it should fix this issue.

The figure labels and references are stylistic choices. Your suggestion of using numbers in the pdf file is definitely another option. Ideally Drasil will allow the user to specify their stylistic choices. This hasn't been a priority, but in the future, the plan is to have this kind of flexibility.

Using the labels PS1, PS2 etc in the figure is a good idea. However, at the moment, the figure is drawn manually, not generated. If we incorporate the labels from the generated file, we run the risk of the figure and the main document not matching in the future, should the document be changed. Ideally, the figures themselves will be generated, but this kind of generation is a long way down the road. :-)

For your fourth point, I believe that the refnames are handled correctly. When the label is shown at the original source it does not have the prefix of its "type" (GS, A, TM etc), but whenever it is used subsequently, the prefix is introduced. Again, different stylistic choices could be made here. There are certainly other options that eventually could be made available to users so that the generated documented can be configured to match the expected style.

Good issues @muralidn. Thank you.