TECHNICAL NOTICE: Moving IATI Standard content from IATI reference site to main IATI website

The IATI Technical Team will shortly be moving the content of the IATI Standard Reference site onto IATI’s main website: iatistandard.org/. This work is being delivered in line with the IATI Workplan Y6 (Sept 2018 - Dec 2019) and IATI Workplan Y7 2020.

This move means that IATI Standard reference information will be accessible on one website, alongside other useful publisher and user content. It will also streamline the Technical Team’s process of updating content, saving valuable time.

What is changing?

Other content to be moved to from GitHub to Wagtail include:

Changes to the format of the IATI-Extra-Documentation GitHub repository - please provide your views

The IATI-Extra-Documentation repository will remain on GitHub however the Technical Team proposes to change the way the pages are written (as described below). Currently the Technical Team uses reStructuredText (rst) format, with additional Sphinx markup. However the additional Sphinx markup added to the files can be a nuisance to read as code and can sometimes be confusing for human reading as well.

The Technical Team propose changing the format of these files into one of two options:

  1. Change the files into JSON format with some embedded Jinja which would link to the example XML files. This would mean it would be easier for developers to obtain the Extra-Documentation content from the repository, and it would correspond with the format that is used by the IATI-Standard-Website.

  2. Change the Extra-Documentation repository into XML formatted files. This would enable developers to easily read and convert the documentation to the required formats, whilst also remaining in a familiar and readable format, allowing for easy generation or amendment of content as necessary.

Feedback required: Please provide your preferred option or any other comments about this proposal by responding to this post or emailing: support@iatistandard.org.

Do note: that the Technical Team will keep sphinx branches in the IATI-Extra-Documentation GitHub repository after the format switch is made. If you wish to keep using them in that format, only a branch switch will be required. However if you wish to use the new format, your work will have to adapt to include them.

What is not changing?

The following content will be accessible on iatistandard.org but will remain on Github and not be moved to Wagtail:

Who will be affected by these changes? Should I do anything to prepare?

Developers who pull guidance content from Github repositories into their own platforms may be affected. If a developer has concerns about the content in the Github repositories that will be moved to Wagtail, please contact the IATI Technical Team: support@iatistandard.org.

If you are not constantly creating guidance pages from the content of the IATI-Guidance or IATI-Extra-Documentation repositories, there’s nothing to prepare for.

Should I be aware of any potential difficulties with these changes?

After IATI Standard guidance moves from reference.iatistandard.org/ to iatistandard.org/, users will no longer be able to access new changes made to the content. Only changelogs will keep a record of new changes, and users will find the changelogs in the IATI-Standard-SSOT GitHub repository.

Will historic GitHub content be accessible to users?

Yes, historic content will still be available to users, as Github keeps control of commits over time.

Will there be French translations of the content moving from the IATI reference site to iatistandard.org?

The following content will be translated into French:

The following content will be automatically generated from the IATI single source of truth, and will remain in English only:

When will these changes happen?

The proposed changes are scheduled to be implemented in early March. Github repositories deletion will only occur once the guidance is moved and deployed to iatistandard.org

Get in touch

If you have any questions about these changes please email support@iatistandard.org or post a comment below.

Many thanks,
IATI Technical Team

1 Like

Thanks for the clear breakdown.

Its probably better to archive, rather than delete GitHub repos.

5 Likes

Thanks for sharing that. Would it be possible to make HTTP 301 (Permanently moved) redirects from the old URLs to the new URLs? That would have two major benefits:

  1. People with old bookmarks, links from social media/email, etc, will still be able to get to the content they’re looking for.

  2. Search engines like Google will recognise the permanent relocation and transfer over the pagerank from the old pages, so they won’t lose their search-engine rankings.

4 Likes

Thanks for the update

As someone who wrote that restructuted text, I follow your quest for a another format!

However, it should be noted that we moved all guidance and documentation content to an openly accessible source (github) precisely because the previous attempt (embedded with a wordpress instance) had reached its limit for a scalable and open standard. I am therefore cautious in terms of the benefits of this proposal

  • Have other approaches been considered? There is a range of possibilities with (for example) static site generators such as readTheDocs. (both Open Contracting and 360Giving use this).

  • Is it possible to provide a preview of any site before any potential switch over?

  • I am unclear on the differences between:

and, then later:

What does this mean to the user that access the schema, schema documentation and codelists on a daily basis?

In terms of version control of our shared resources:

  • How will guidance documentation be version controlled? If content will no longer exist in GitHub, how can issues be raised, pull requests be submitted, and fixes be reviewed and merged, etc?

  • Where does this fit with the version control of the whole standard? The SSOT is meant to encompass schema, codelists, rulesets and (alas) guidance/narrative documents. How do we now govern this?

  • In terms of the last two points, I would encouraged the secretariat to look more closely at the policies developed elsewhere for normative and non-normative content. These can really help us, if we are to have a discussion about the differences between the standard to adhere to and guidance to help implement it. It’s a thorny subject - and not, imho - solved by a switch of backend

Thanks

2 Likes

Its probably better to archive, rather than delete GitHub repos.

Yes, the intention would be to move these (and several old tools), to an “Archived” repository. However, this removal + move will happen further down the line.

2 Likes

Would it be possible to make HTTP 301 (Permanently moved) redirects from the old URLs to the new URLs?

Yes absolutely, the intention is to make the move as seamless as possible. Redirects will be put in place from reference.iatistandard.org to iatistandard.org for both guidance and documentation pages.

2 Likes

Thanks for the opportunity to feed into this consultation and for all the work already done on this. In principle it will be great for the reference pages to get a refresh and to have a consistent theme with the rest of the IATI site, as well as to improve the navigation between the two.

I agree with several of the other comments here, and would just emphasise that I think it is important that all of the IATI Standard remains version controlled (I think this should definitely include the guidance materials) and that there is transparency around changes and which version is shown at a particular time.

For these reasons, I do like the approach that Open Contracting (mentioned above) uses. I am a little bit nervous about the idea of putting all of the Standard into the database behind the Wagtail system (I assume this is what is planned?) because it could make it much harder to track changes over time.

But I guess using Wagtail it could also be possible to achieve version control and transparency, depending on the implementation – can you give us some more details on how Wagtail would determine which version of the SSOT to show - and how users would know which version was being displayed? Would this be automated, e.g. the latest version of a particular branch on Github? (I understand from all this that the SSOT would continue to be managed on Github.)

Many thanks!

1 Like