This post aims to explain the Technical Team’s final proposal on changing the Github SSOT repositories and developer documentation (following discussions and considerations of your responses to our initial post). We aim to get approval from the community and request that you respond to this post by Friday 27 March.
1. Single Source of Truth (SSOT)
Currently, in the SSOT repository on Github we have:
- Codelists
- Extra Documentation
- Rulesets
- Schemas
What changes do we want to make to the SSOT Github repository?
Location of files
The changes we want to make refer to specific sections of the Extra Documentation only.
In Extra Documentation we currently have:
-
Activity standard
- IATI activities
- Overview
- [Separate RST files]
-
Codelist guides
- Codelist API
- Codelist Management
- Codelists
-
Organisation standard
- IATI organisations
- Overview
- [Separate RST file]
-
Rulesets
- Ruleset development
- Standard rulesets
See the Table Changes to the SSOT- Extra Documentation, detailing specific changes and where files will be relocated to.
Format of files
We had initially proposed to change the format of the IATI Guidance and IATI Extra Documentation repositories and were considering changing their content to XML formatting. There were no strong views expressed from the community on IATI Discuss and following discussion with Open Contracting and considering options with other developers, we have decided to keep files in the format they currently are in: RST.
RST is still widely used by data standards organisations for documentation because it is easy to read, easy to version control, and can still contain a robust amount of content and formatting. While XML or JSON would have been more flexible and more machine readable, it would not be human readable, nor would it be easy for the community to version control.
Why are we making these changes to the SSOT repository?
The SSOT needs to cover only the prescriptive parts of the Standard and needs to be version controlled for each version of the Standard, e.g 2.01, 2.02, 2.03. The content that we want to move out of the SSOT repository is the descriptive part of the standard, including guidance and explanations. Based on feedback received from the community on how important version control is for the descriptive part of the Standard, we have decided to keep all existing content from Extra Documentation on Github and will simply change the location of the files; it will still be version controlled on Github but only for major versions of the Standard.
2. Developer Documentation
In our previous Technical Notice post we have announced that we will be moving the Developer Documentation to our Content Management System (CMS) Wagtail, meaning it will not be version controlled. We have not received any objection to this from the community so would like to go ahead with that change and wanted to confirm that in this post.
Get in touch
Please let us know your views by responding to this post. If you can let us know your views by next Friday 27 March, that will be much appreciated!
If you have any questions about these changes please email support@iatistandard.org