Closed KathiSchleidt closed 2 months ago
Assure that grey scale images are readable.
During discussions at the ISO plenary, I learned that there IS an example of an ISO standard with colors in the UML (just forgot which one :( ). When discussing this with Jay Last, one should point out that color in boxes is valuable in expressing what is an interface vs. class. The colored associations do get a bit strange, as the relatedObservation is the inverse of many of the core associations. Maybe only use green when ONLY the relatedObservation, revert to black where there is an inverse
-003 Colour indicates meaning: Decided in the SWG meeting on 8th June to turn all the associations with a role name relatedObservation
from green to black, and keep the metadata association lines as cyan. Also decided to try and remove the gradient background color of the classifiers to improve readability, but to keep the interfaces colored to improve readability.
-002 Text not readable: Need to check all of the Figures for text content in English (other than the names to the classes and their properties) and remove move that to the Figure caption. Otherwise translation would be difficult. Also need to scan all of the Figures for text appearing smaller than text in 8tp font on the page and find a way to increase its apparent size when the image is put on the page.
-002: Due to the limited page width in A4 I probably have to either considerably re-arrange the UML context diagrams to make them less wide and taller, or to take out some of the UML context classes from the diagrams.
Additional note to remember from the time of the DIS Ballot submission: We had to submit all the Figures as PNG rather than EMF, as the publication process is based on intermediate XML format from which the final publication formats are generated. The Figures are submitted separately and fed into the XML process along with the textual content in Word format. Thus: no need to generate the EMF files, as they are not used in the final spec anyway.
I've done a test to see how the images come out in grey scale, mostly readable (collection under https://github.com/opengeospatial/om-swg/tree/master/oms-abstract-spec/figures/BW_Test)
There is currently an issue with Basic Observations, one association goes diagonally across the page
The images mostly work in grey scale, 2 comments:
The real challenge is the make the text in UML diagrams "certainly no smaller than 8tp" when embedded in the document. I really see only two options for us to fulfil this requirement:
I could try to create a couple of test diagrams to see how those options would look like.
How about the following compromise:
I don't see how keeping the diagrams with smaller-than-8pt and adding ones with the same classes with-bigger-than-8pt solving to (bureaucratic) issue of having some diagrams with too small font
I like the idea to only show the relations for the immediately related classes (option 2) since it makes the diagram a lot clearer. The mess of arrows in the top box in option 1 is totally unreadable any way, so it's better to leave that out. It may need a disclaimer stating which classes have all their relations, and that for other classes the relations are left out.
If we apply the same logic for all of the UML context diagrams, we can state it under Clause 4 Document conventions. We have to clean-up all text from the diagrams anyway, so alternatively the information about which classes have hidden attributes and associations would be written as notes in the document text under each Figure.
I also tested to actually print the diagram pages from Word as B/W, and the cyan metadata lines + labels appear as really pale, almost invisible. So I would propose we turn them into regular dark grey like we already decided to do with the relatedObservation associations
I would also turn the background color of the package boxes from EA default to white and get rid of the gradient fills of the classes and interfaces
Proofs (printed + scanned by mobile) of the original + the option 2 in color & B/W
Proposal: Redraw all the UML context diagrams
Looking at the proofs, the final one (option 2 BW) is definitely the most readable
Only thing that worries me is not providing the big picture diagrams in addition - some folks may be able to keep all the info from the previously viewed diagrams in their head, but I tend to need a BIG picture - think we can slip in somehow (true pity they don't use the svg images, that would allow readers to scale as they like on a screen or worst case do an A0 printout of stuff they really wanna digest)
A bit late to the party.
To clarify: the proof page on the right is the same as the one in the middle, just printed as B/W by the printer. Do you still want to keep the color fills of the classes and interfaces or really turn all the UML diagrams BW in the Word doc?
I remember that we talked about having wider diagrams in informal Annexes before, it was probably about the requirement graphs at that point. I don't remember if we got any definitive answer from Mats whether the less-than-8pt-font would also be an issue in an informal annex if the same information would also be included in parts in the normative content.
Perhaps worth another specific question by mail. [edit: I just asked this by email from Jay Last of ISO]
Additionally: make the attribute text black instead of dark red
Option 2 looks best, should be used in normative clauses 8-13
Add full diagrams to new Annex E in color
Ask Peter Parslow for help!
Open is if we make Annex E Normative or Informative
Examples of the re-drawn UML Diagrams pushed to repo at https://github.com/opengeospatial/om-swg/blob/master/oms-abstract-spec/figures/final-iso-19156/
Re-drawn Figures 1-23, E.1 (Abstract Observation core - overview) and E.2 (Basic Observations - overview) as EMF + PDF now available in GitHub at abstract-spec/figures/final-iso-19156.
File naming now follows the naming convention in Requirements and guidelines for the submission of drafts to ISO/CS:
StandardNumber-partNumber_editionNumber/figureNumber e.g. For the first edition of ISO 12345-1, figure files should be named as 12345-1_ed1fig1.dwg, 12345-1_ed1fig2.ai, etc... For figure files in an annex (e.g. Annex A), they should be named 12345-1_ed1figA1.dwg, 12345-1_ed1figA2.ai, etc
The numbering shifted by one from number 15 forward, see #207
Figures 24-36, C.1, C.2, D.1, D.2, D.3, D4, D.5, E.3 (Abstract Sample core - overview) and E.4 (Basic Samples - overview) still TODO
Figures 24-36, C.1, C.2, D.1, D.2, D.3, D4, D.5, E.3 and E.4 added to abstract-spec/figures/final-iso-19156.
UML diagrams ready for cross-check
Add revised Figures now added to the Word document, as well as the new Annex E
Why couldn't this be cross-checked?
this one is still todo for me
cross-checked down to fig14
- 19156_ed2fig3 : name is truncated to 'object Figure 3: Model Consi...
I'll try to make the diagram a bit wider to keep the name untruncated.
- 19156_ed2fig9 : pointing to /rec/obs-cpt/Observation/observedProperty-con. cross checking, I see we also have /req/obs-core/Observation/observedProperty-con. Both with same content "The ObservableProperty referenced by observedProperty should correspond to a characteristic associated with the featureOfInterest"" -> duplicate ?
In the conceptual obs. schema the obs.prob. con is a recommendation (rec
) and in the abstract obs. core it is a requirement (req
). On the other hand I'm not sure if we should list recommendations as UML class constraints at all, opinions?
- 19156_ed2fig10 : why pointing to only one - sem in the constraints of the AbstractObservation ? Sorry if we decided it at some point, just don't recall
The /req/obs-core/AbstractObservation/observationType-sem is actually a constraint requiring other possible constraints to be applied based on the used observationType. Should this be a -con
instead?
In the conceptual obs. schema the obs.prob. con is a recommendation (rec) and in the abstract obs. core it is a requirement (req)
I know but I don't remember why we have 2 of them actually with the same content
On the other hand I'm not sure if we should list recommendations as UML class constraints at all, opinions?
That's linked to my comment on the -sem. While cross-checking I was actually trying to check if the req / rec mentionned were actually in the doc and vice versa if we were not missing some from the doc (actually we don't have many -sem from the doc in the UML as constraints, we just need to be coherent altogether)
The only difference between the rec and req statements is the use of "should" vs. "shall"
But, ALL req should be in the UML for consistency
@KathiSchleidt: by "ALL req" do you mean all the requirement statements in the spec? Currently we basically only have the "-con" requirements and recommendations in the UML model as constraints (that's why they have the -con" postfix). The "-sem" text is copied to UML class, attribute and association descriptions, but not verbatim: Interface Host has description of "a grouping of Observers for a specific reason." while the /req/obs-cpt/Host/Host-sem states "A Host shall be defined as a grouping of Observers for a specific reason."
The abstract core and basic packages (mostly?) import the cpt requirements, but those classes still still need UML descriptions. The AbstractHost is described as "A FeatureType realization of Conceptual Observation Schema:Host" and the Host (in Basic Obs.) as "Concrete class for expressing a realization of Conceptual Observation Schema:Host interface based on General Feature Model as defined in ISO 19109"
I guess it would still be doable to amend the current UML class description texts with the corresponding requirements class URIs in the spec, if that would seem helpful.
Alternatively, there should at least be a statement somewhere in the text that only the -con reqs are provided in the UML, the -sem requirements are covered by the definitions
ok, seems we are converging. I like Kathi's proposal. Don't know if that's worth the effort to edit all classes description to add "description texts with the corresponding requirements class URIs" let's discuss this at today's meeting
Agreement KS diagrams, SWG 19.10.22
Both req and rec are to be listed in the UML classes, except for the defining -sem req, as this information is provided in the notes on the class.
addition to the meeting decision .... except for the defining -sem req (as...see above...), -card req (as this information is provided in the UML schema)
Feedback on Observation : Conceptual, Abstract, Basic
class Figure 9: Conceptual Observation schema - overview /rec/obs-cpt/Observation/phenomenonTimeResult-con : missing
class Figure 10: Context diagram: AbstractObservation, AbstractObservationCharacteristics
AbstractObservationCharacteristics
/rec/obs-core/AbstractObservationCharacteristics/parameter-procedure : missing
/rec/obs-core/AbstractObservationCharacteristics/parameter-redundant : missing
/rec/obs-core/AbstractObservationCharacteristics/uFoI : missing
AbstractObservation
Observation
figure 11, 12, 13, 14, 15, 16, 19, 20, 21, 22, 23: same as Figure 9
figure 16
figure 17, 18, 24 : same as figure 10
will continue with the Sample schemas tomorrow
Feedback on the Sample
Thanks @sgrellet for crosschecking! I agree with most, but not all:
* AbstractObservation * /req/obs-cpt/Observation/phenomenonime-card : should be removed, not coherent with figure 9 (no card that restate the UML) * /req/obs-cpt/Observation/resultTime-card : should be removed, not coherent with figure 9 (no card that restate the UML) * /req/obs-cpt/Observation/observedProperty-card : should be removed, not coherent with figure 9 (no card that restate the UML) * /req/obs-cpt/Observation/observingProcedure-card : should be removed, not coherent with figure 9 (no card that restate the UML) * /req/obs-cpt/Observation/result-card : should be removed, not coherent with figure 9 (no card that restate the UML)
These are marked here as constraints, because the cardinalities inherited from AbstractObservationCharacteristics are more relaxed (0..n). It would not be clear that the realization of the Observation interface would impose tighter attribute cardinalities (1 or 1..*) over the ones inherited from the parent class. Also based on input from Clemens Portele the constraints are not inherited with interface realization, and thus must be duplicated in the FeatureType classes.
Feedback on the Sample
class Figure 25: Conceptual Sample schema - overview
- has no 'Constraints' while in every previous schema, 'Observation' interface do display its constraints : we not coherent in our overview schemas
- Figure 26: same as 25
Figure 31: Context Diagram: Sample
- on SampleTypeByGeometryType {/req/sam-basic/SampleTypeByGeometryType-con} -> should be {/req/sam-basic/SampleTypeByGeometryType/SampleTypeByGeometryType-con}
I'll implement these fixed for the Sample schemas also as soon as the ISO ProCloud server is up again (a really bad timing for it being down).
question on 19156_ed2fig D2 and D4, D5
- should we precise +(ultimate|proximate)FeatureOfInterest on the association roles or am I being too precise for the purpose of this informative annex ?
I would not touch the Annex D Figures at this point
@ilkkarinne : ok, you're right. I agree with all your replies
Figures now updated in GitHub figures folder, figure update to the specification document still TODO
All fixes for Figures readability are now done, pending final cross-check on the Word document contents, the file version is available at https://github.com/opengeospatial/om-swg/blob/565e9bcda60f02cfafa24ea85bc302828c2e999d/oms-abstract-spec/ISO%20DIS/ISO_DIS%2019156%20ed.2%20-%20id.82463%20Enquiry%20Trackchange%20Word%20(en).docx
Cross-checked by @KathiSchleidt, moving to implementation cross-checked
Comments:
-002 Text not readable. We require readable text, in that when the figure is presented at the scale of the document page, text is ideally at a size of 10pt, and certainly no smaller than 8pt. Please reconfigure the figure to enable a larger text size, or remove some text to allow more space for the remaining text. Figures should also be language neutral. Please remove all language text from the figure and replace it with an item reference or footnote. Add the removed text to the key below the figure. Please contact Jay Last ( last@iso.org ) for any figure related questions.
-003 Colour indicates meaning. We require that colour should not be used to indicate meaning in the figure, for reasons of accessibility for all users of the document. Please find another way of differentiating lines, groups or stages, for example using differently dashed lines and containing rectangles, using clearly discernible shades of grey instead of colours, or using footnotes to indicate meaning. Figures should not simply be made into greyscale as this does not help with regard to meaning. When possible the figures should be drawn in simple black and white for the best clarity.
KS -002 Text not readable, would be interesting what this pertains to, assuming the UML. There we have the question of how to provide the UML, if their pages are too small ;)
KS -003 Colour indicates meaning: we should check if the images work in grey scale, maybe adjust accordingly. I'd try and maintain the color as long as its also legible in BW