technical writing - documentation improvements - IES-Top

[GabrielB-SP]

Hello!
This is a pull request regarding some documentation improvements for ies-top:

• formatting issues: new lines that were interrupting paragraphs, extra spaces, typos, bulletpoints
• hyperlinking: live links to documents within the repo
• slightly modified formatting in ies-top.md for easier markdown maintenance
• core files needed at the root level of the the repo: contributing, maintainers, notice
• mailto links for opening a page in the user's email service and helping them compose a contact email from a template
• ToCs where needed

Best regards,
Gabriel

[nigel81562]

Appreciate these documentation updates are largely cosmetic and intended for consistency across the IES repos. However, IES-top (and IES-Core) are the foundational modules (Layer-1 and Layer-2) which are to be more tightly governed by the IES technical group generally, and by the deep experts more specifically. This should not affect users and groups developing IES extensions (i.e. other IES modules), and is to ensure stability and foundational consistency and integrity. The rest of IES has dependent upon these foundations. As such the Contributing and Maintainers information needs amending from the general wording to reflect governance by the module's technical experts. This in no way affects licensing, ownership, etc.

[aigora-de]

Appreciate these documentation updates are largely cosmetic and intended for consistency across the IES repos. However, IES-top (and IES-Core) are the foundational modules (Layer-1 and Layer-2) which are to be more tightly governed by the IES technical group generally, and by the deep experts more specifically. This should not affect users and groups developing IES extensions (i.e. other IES modules), and is to ensure stability and foundational consistency and integrity. The rest of IES has dependent upon these foundations. As such the Contributing and Maintainers information needs amending from the general wording to reflect governance by the module's technical experts. This in no way affects licensing, ownership, etc.

@nigel81562 thank you for highlighting this. Two thoughts:

1. ACKNOWLEDGEMENTS.md, the section Organisational Contributors may need updating to list core contributing orgs
2. Changes to the boilerplate content that you refer to should probably go to the IES-SG for approval - perhaps as an issue raised in IES Governance

[nigel81562]

Appreciate these documentation updates are largely cosmetic and intended for consistency across the IES repos. However, IES-top (and IES-Core) are the foundational modules (Layer-1 and Layer-2) which are to be more tightly governed by the IES technical group generally, and by the deep experts more specifically. This should not affect users and groups developing IES extensions (i.e. other IES modules), and is to ensure stability and foundational consistency and integrity. The rest of IES has dependent upon these foundations. As such the Contributing and Maintainers information needs amending from the general wording to reflect governance by the module's technical experts. This in no way affects licensing, ownership, etc.

@nigel81562 thank you for highlighting this. Two thoughts:

1. ACKNOWLEDGEMENTS.md, the section Organisational Contributors may need updating to list core contributing orgs
2. Changes to the boilerplate content that you refer to should probably go to the IES-SG for approval - perhaps as an issue raised in IES Governance

Already approved by SG - i.e. process proposed by Paul L. More specifically for top, as agreed by TG, the critical dependency and deep nature require tighter expert maintenance, and (min) two reviewers from TG. @afizzycola reflecting this with 3 roles to be filled from TG, essentially following Paul's process. The documentation should reflect the implementation.

[afizzycola]

This document is generated from the master UML model hence you cannot just make changes to the format and structure here. Hence please leave this document alone. If you have suggestions for its improvement please raise this as issues on this repo. These changes can then be considered to be added to the code which generates the document.

[nigel81562]

For future may be worth adding boilerplate in generation for generated documentation files as to their nature as such. May help to avoid misplaced post-edits in future.

[afizzycola]

The carriage return between line 3 and 4 hasn't seemed to have worked. See below:

The carriage returns seems to be working properly with other .mds

[afizzycola]

Suggested change

	**Repository:** `Information Exchange Standard (IES) - Top Ontology`
	**Repository:** `IES Top Ontology (ies-top)`

For branding reasons we would like to succinctly refer to this as IES Top hence the string used previously was intentional

[afizzycola]

Suggested change

	**Repository:** `Information Exchange Standard (IES) Top Ontology`
	**Repository:** `IES Top Ontology (ies-top)`

As mentioned above, for branding reasons we would like to succinctly refer to this as IES Top hence the string used previously was intentional

[afizzycola]

Fine but this is just a rearrangement of whitespace. Nothing content-wise has changed here

[afizzycola]

Suggested change

	**Repository:** `Information Exchange Standard (IES) Top Ontology`
	**Repository:** `IES Top Ontology (ies-top)`

As mentioned above, for branding reasons we would like to succinctly refer to this as IES Top hence the string used previously was intentional

[afizzycola]

Suggested change

	**Repository:** `Information Exchange Standard (IES) Top Ontology`
	**Repository:** `IES Top Ontology (ies-top)`

As mentioned above, for branding reasons we would like to succinctly refer to this as IES Top hence the string used previously was intentional

[afizzycola]

Suggested change

	**Repository:** `Information Exchange Standard (IES) Top Ontology`
	**Repository:** `IES Top Ontology (ies-top)`

[afizzycola]

Please remove this section, as mentioned above we will add details of the how contributions can be made

[afizzycola]

Suggested change

	**Repository:** `Information Exchange Standard (IES) Top Ontology`
	**Repository:** `IES Top Ontology (ies-top)`

[nigel81562]

Appreciate these documentation updates are largely cosmetic and intended for consistency across the IES repos. However, IES-top (and IES-Core) are the foundational modules (Layer-1 and Layer-2) which are to be more tightly governed by the IES technical group generally, and by the deep experts more specifically. This should not affect users and groups developing IES extensions (i.e. other IES modules), and is to ensure stability and foundational consistency and integrity. The rest of IES has dependent upon these foundations. As such the Contributing and Maintainers information needs amending from the general wording to reflect governance by the module's technical experts. This in no way affects licensing, ownership, etc.

@nigel81562 thank you for highlighting this. Two thoughts:

1. ACKNOWLEDGEMENTS.md, the section Organisational Contributors may need updating to list core contributing orgs
2. Changes to the boilerplate content that you refer to should probably go to the IES-SG for approval - perhaps as an issue raised in IES Governance

Already approved by SG - i.e. process proposed by Paul L. More specifically for top, as agreed by TG, the critical dependency and deep nature require tighter expert maintenance, and (min) two reviewers from TG. @afizzycola reflecting this with 3 roles to be filled from TG, essentially following Paul's process. The documentation should reflect the implementation.

On 'ACKNOWLEDEMENTS.md' contributors section pt - agreed. BORO/Telicent plus certain HMG individuals for this module. In general acknowledgements for different modules would be variable according to provenance of development thereof. Where module extends or leverages other modules then acknowledgment of use of those modules (and thereby the contributors to those modules) should probably be made. This isn't the case for top because, well it is at the top!

[nigel81562]

Text and content no longer appropriate for modularisation. Whilst listed organisations have contributed elsewhere in the development of IES as a whole, this section should reflect those that have provided input into ies-top specifically. As far as I'm aware this includes Telicent/BORO, caesersystems and HMG (defence and security research depts.)

typo 'knowledgethat' -> 'knowledge that'

[afizzycola]

The logo looks worse than previous. Please revert

[afizzycola]

Same edit suggests as above.

[aigora-de]

Appreciate these documentation updates are largely cosmetic and intended for consistency across the IES repos. However, IES-top (and IES-Core) are the foundational modules (Layer-1 and Layer-2) which are to be more tightly governed by the IES technical group generally, and by the deep experts more specifically. This should not affect users and groups developing IES extensions (i.e. other IES modules), and is to ensure stability and foundational consistency and integrity. The rest of IES has dependent upon these foundations. As such the Contributing and Maintainers information needs amending from the general wording to reflect governance by the module's technical experts. This in no way affects licensing, ownership, etc.

@nigel81562 thank you for highlighting this. Two thoughts:

1. ACKNOWLEDGEMENTS.md, the section Organisational Contributors may need updating to list core contributing orgs
2. Changes to the boilerplate content that you refer to should probably go to the IES-SG for approval - perhaps as an issue raised in IES Governance

Already approved by SG - i.e. process proposed by Paul L. More specifically for top, as agreed by TG, the critical dependency and deep nature require tighter expert maintenance, and (min) two reviewers from TG. @afizzycola reflecting this with 3 roles to be filled from TG, essentially following Paul's process. The documentation should reflect the implementation.

Yes, didn't mean to imply the governance side of things, just the docs. As with the branding mentioned below and your comment about "adding boilerplate in generation for generated documentation files", we are trying to manage the boilerplate content and changes across all repos to make it more consistent and easier to maintain. What I was trying to say, is that we need to take that into account during the review process. I'm personally ok with the idea that it may vary (e.g. for IES Top), but simply this needs to be done in the round to avoid playing boilerplate tennis.

[nigel81562]

Appreciate these documentation updates are largely cosmetic and intended for consistency across the IES repos. However, IES-top (and IES-Core) are the foundational modules (Layer-1 and Layer-2) which are to be more tightly governed by the IES technical group generally, and by the deep experts more specifically. This should not affect users and groups developing IES extensions (i.e. other IES modules), and is to ensure stability and foundational consistency and integrity. The rest of IES has dependent upon these foundations. As such the Contributing and Maintainers information needs amending from the general wording to reflect governance by the module's technical experts. This in no way affects licensing, ownership, etc.

@nigel81562 thank you for highlighting this. Two thoughts:

1. ACKNOWLEDGEMENTS.md, the section Organisational Contributors may need updating to list core contributing orgs
2. Changes to the boilerplate content that you refer to should probably go to the IES-SG for approval - perhaps as an issue raised in IES Governance

Already approved by SG - i.e. process proposed by Paul L. More specifically for top, as agreed by TG, the critical dependency and deep nature require tighter expert maintenance, and (min) two reviewers from TG. @afizzycola reflecting this with 3 roles to be filled from TG, essentially following Paul's process. The documentation should reflect the implementation.

@aigora-de - just to be clear on this, I would expect SG approval/assurance that changes for these documents for layer-1 (and corresponding ones for layer-2) that they do reflect the agreed process. But they need to be available for comment and for TG to make recommendation.

[GabrielB-SP]

I have made the following changes to this PR, according to all the reviews and feedback.

• fixed carriage return where it was an issue
• listed companies correctly in ACKNOWLEDGMENTS.md
• reverted all changes to ies-top.md and created an issue where I mentioned recommendations for it and other sections in the repository
• removed "readme.MD" from /spec/validation_artefacts and merged its contents into spec/index.md
• kept the name Information Exchange Standard (IES) - Top Ontology to stay in line with the naming convention from other IES repositories, i.e. Information Exchange Standard (IES) - Repository name
• kept ToCs where possible, even if documents are small, this falls in line with the other repositories
• kept hyperlinks to other files where possible, it's generally good to have as many cross-references as possible, to give the reader the ability to easily navigate from one place to the other. While this doesn't seem very useful for a small repository, it's a good practice that should be maintained across all repositories
• removed mentions of files when describing the structure of specs/validation_artefacts and kept only the folders, not the files
• seeing that there's another PR related to CONTRIBUTING.md and MAINTAINERS.md, I removed them from my PR. If needed, you can check my branch for previous versions and their content.
• corrected the logo where it looked worse than before

Thank you again for your very thorough feedback!
@afizzycola @nigel81562 @ndtppd @ndtppm