search

opengeospatial / om-swg

10 stars 6 forks source link

Figures Readability #164

Closed KathiSchleidt closed 2 months ago

KathiSchleidt commented 2 years ago

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

KathiSchleidt commented 2 years 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

ilkkarinne commented 2 years ago

-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.

ilkkarinne commented 2 years ago

-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.

KathiSchleidt commented 2 years ago

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:

ilkkarinne commented 2 years ago

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:

  1. If we want to keep as many of the other classes in the context diagrams, we can hide all the attributes (and operations) of other than classes than the one which the context diagram is about. For clarity I would still keep all the associations of the context classes visible, as well as show inherited attributes in the class at focus of a particular diagram.
  2. We include only the immediately related classes in context diagrams (only the immediate ancestor with inherited attributes + the interface realized + immediately associated classes).

I could try to create a couple of test diagrams to see how those options would look like.

KathiSchleidt commented 2 years ago

How about the following compromise:

ilkkarinne commented 2 years ago

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

ilkkarinne commented 2 years ago

Alternative diagram layout examples for Figure 15: Basic Observations - Observation:

hylkevds commented 2 years ago

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.

ilkkarinne commented 2 years ago

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.

ilkkarinne commented 2 years ago

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

ilkkarinne commented 2 years ago

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

ilkkarinne commented 2 years ago

Proofs (printed + scanned by mobile) of the original + the option 2 in color & B/W

ilkkarinne commented 2 years ago

Proposal: Redraw all the UML context diagrams

KathiSchleidt commented 2 years ago

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)

sgrellet commented 2 years ago

A bit late to the party.

ilkkarinne commented 2 years ago

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]

ilkkarinne commented 2 years ago

Additionally: make the attribute text black instead of dark red

KathiSchleidt commented 2 years ago

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!

KathiSchleidt commented 2 years ago

Open is if we make Annex E Normative or Informative

ilkkarinne commented 2 years ago

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/

ilkkarinne commented 2 years ago

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

ilkkarinne commented 2 years ago

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

ilkkarinne commented 1 year ago

Add revised Figures now added to the Word document, as well as the new Annex E

KathiSchleidt commented 1 year ago

Why couldn't this be cross-checked?

sgrellet commented 1 year ago

this one is still todo for me

sgrellet commented 1 year ago

cross-checked down to fig14

ilkkarinne commented 1 year ago
  • 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?

sgrellet commented 1 year ago

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)

ilkkarinne commented 1 year ago

The only difference between the rec and req statements is the use of "should" vs. "shall"

KathiSchleidt commented 1 year ago

But, ALL req should be in the UML for consistency

ilkkarinne commented 1 year ago

@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"

ilkkarinne commented 1 year ago

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.

KathiSchleidt commented 1 year ago

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

sgrellet commented 1 year ago

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

KathiSchleidt commented 1 year ago

Agreement KS diagrams, SWG 19.10.22

KathiSchleidt commented 1 year ago

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.

sgrellet commented 1 year ago

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)

sgrellet commented 1 year ago

Feedback on Observation : Conceptual, Abstract, Basic

will continue with the Sample schemas tomorrow

sgrellet commented 1 year ago

Feedback on the Sample

ilkkarinne commented 1 year ago

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.

ilkkarinne commented 1 year ago

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

sgrellet commented 1 year ago

@ilkkarinne : ok, you're right. I agree with all your replies

ilkkarinne commented 1 year ago

Figures now updated in GitHub figures folder, figure update to the specification document still TODO

ilkkarinne commented 1 year ago

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

ilkkarinne commented 1 year ago

Cross-checked by @KathiSchleidt, moving to implementation cross-checked