Changes to Github SSOT repository & developer documentation- please comment by 27 March

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:

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

2 Likes

We have not received any comments from the community by the deadline of the 27th of March. As a result, we assume that there are no objections and the IATI Tech Team will proceed with the SSOT changes as outlined in this thread!

Do get in touch if you need any further clarification on any of the information we have provided above!

1 Like