[Rats] FAO Architecture sub-group, new issue added

[Simon Frost <[e-mail]>]

FAO the architecture sub-group

I've opened a new Issue on the doc to query the readability flow of the document:
https://github.com/ietf-rats-wg/architecture/issues/163
As part of a review of the document by the Arm team, the document was shown to someone less familiar with the area. Their feedback was that they found the flow of the document hard to follow, with the comments that the terminology section was too remote from the core architecture discussion. Further, within the Terminology section itself the alphabetic layout was not helpful as they had to go back and forth as they tried to understand the terms. The suggestion was to use a more hierarchical layout for the terminology.

I've also created a PR (https://github.com/ietf-rats-wg/architecture/pull/164) with a proposed change to the flow to address this. The changes are based on some experimental reworks of the doc that tested well in review locally. The core definitions / descriptions within Use Case / Terminology  have not been changed from the current -07 state.

Summary of changes:

+ Moved the 'scene setting' Use Cases section to follow the Introduction  (the text here is general, without really needing use of the specific terminology)
+ Remove specific terminology (Attester / RP) from the Use Cases section by generalising the language used, while keeping the clarification of those parties. This allows the Terminology section to move...
+ Terminology section now follows Use Case section, which puts it next to the Architecture section, and in particular Fig1, where understanding of the terminology is most needed.
+ Change alphabetic layout of Terminology section to be more hierarchical on use/importance of terms (split into Roles & Artifacts and ordered so that the more important term lead)
+ Added relationship descriptions between terminology entries.
Thanks
Simon

Simon Frost
Senior Principal Systems Solution Architect, ATG, Arm
Mob: [phone]


IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.