Add guidance

[jpmckinney]

• Integrate content from CRM-3987
• Describe multilingual support (the schema page links to a #multilingual-support anchor)
  • Can link to http://standard.open-contracting.org/latest/en/schema/reference/#language
• Uncomment the three occurrences of the 'documentation' link
• Ensure the content covers https://www.open-contracting.org/tag/extensions/ and links to the schema style guide
• Add content relevant to passing extension review (see internal process document)
  • Consider which of the review criteria to add to the readmes of the extension registry or extension template
• Explain that extension authors just need their extension versions added to the registry to appear in the explorer
• Decide whether to move content from the extension template to either the explorer or the standard documentation
  • This content might be split into multiple pages.
  • If moved, we can replace the extension template readme with sample headings and expand on what makes good documentation

[jpmckinney]

• Describe Extension Creator and provide (or link to) instructions
• Make sure https://www.open-contracting.org/2018/01/30/fields-dont-map-first/ is integrated
• Make sure https://www.open-contracting.org/2018/07/16/creating-managing-ocds-extensions/ is integrated

[duncandewhurst]

It would be great to progress this since we are still directing publishers to https://www.open-contracting.org/2018/07/16/creating-managing-ocds-extensions/ which is getting quite out of date (it doesn't mention the extension explorer, for example).

[jpmckinney]

The document in CRM-3987 was drafted a couple years ago, and isn't the same level of clarity and quality as more recent documentation. Can you edit it accordingly? If possible, it'd be good to complete the above tasks, too.

I had started integrating the content in July, but didn't get past the home page. The content needs to start simpler, e.g.

• For publishers: "OCDS defines a core set of fields with which publishers describe contracting processes. Additional fields outside the core set can be described by extensions. …"

• For users, the focus is on understanding the data, looking up fields and codes – it shouldn't be in terms of learning what changes different extensions make: "To use data, you first need to understand it. OCDS data contains fields from: (1) OCDS, whose fields are described in its schema and in its Schema Reference [link]; (2 )extensions, whose fields are described in their schema and on their webpages. To see which extensions are in use, you can either: (1) Open the OCDS data in a text editor. If it uses extensions, it sets an extensions field, which is an array of URLs to extension.json files. If you open a URL, you will see a documentationUrl object, with a URL to the extension's documentation. Open the URL to read its documentation (in many cases, the URL leads to this website). (2) Upload the OCDS data to the Data Review Tool [link], which lists the extensions it uses and links to their documentation. …"

[duncandewhurst]

• Integrate content from CRM-3987

I've edited the document. Do you want to review it before I create a PR?

• Describe multilingual support (the schema page links to a #multilingual-support anchor)
• Can link to http://standard.open-contracting.org/latest/en/schema/reference/#language

I'm not sure what's needed here and who the audience is - is it publishers or users? For publishers, do we need to explain the use of patternProperties for language-suffixed fields somewhere? I think the standard development handbook might be the best place for that.

• Add content relevant to passing extension review (see internal process document)
• Consider which of the review criteria to add to the readmes of the extension registry or extension template

I've integrated the criteria from the 'quick checks' section of the process note, but left the 'in-depth checks'. Potentially, we could add the criteria under the 'individual files' subheading to the extension registry readme.

• Decide whether to move content from the extension template to either the explorer or the standard documentation
  • This content might be split into multiple pages.
  • If moved, we can replace the extension template readme with sample headings and expand on what makes good documentation

There's a lot to integrate here and I don't think the current location is causing any problems, so I suggest we keep it as-is and open a follow-up issue on integrating it (if there is a need/demand). Does that sound good?

• Make sure https://www.open-contracting.org/2018/01/30/fields-dont-map-first/ is integrated

The guidance in this blog is more about the process for mapping additional fields than it is about using or creating extensions. I think it would fit better under https://standard.open-contracting.org/latest/en/guidance/map/#consider-using-extensions, The information that is not repeated elsewhere can be boiled down to:

Before using extensions, you should decide whether the additional data that you want to disclose affects how users should interpret fields in the OCDS schema. If so, consider whether you can include extra information in an existing field to alert users who only know about fields in the OCDS schema. For example, to disclose data about the disposal of state assets, in addition to using an extension, you can prefix tender.title with 'Disposal:'.

You should also double-check whether the additional data that you want to disclose can be modelled using an existing field. For example, to disclose the date by which the procuring entity will respond to enquiries, rather than adding a field, you can use tender.milestones.

What do you think?

• Make sure https://www.open-contracting.org/2018/07/16/creating-managing-ocds-extensions/ is integrated

Once the Extension Explorer is updated, we should add a note to this blog to direct readers to the updated guidance.

[jpmckinney]

• Integrate content from CRM-3987

I've edited the document. Do you want to review it before I create a PR?

No, let's integrate what you have, and we can always edit it later.

• Describe multilingual support (the schema page links to a #multilingual-support anchor)
• Can link to http://standard.open-contracting.org/latest/en/schema/reference/#language

I'm not sure what's needed here and who the audience is - is it publishers or users? For publishers, do we need to explain the use of patternProperties for language-suffixed fields somewhere? I think the standard development handbook might be the best place for that.

I think I intended this for the publisher, to know that they don't need to define fields for different languages, and that they can instead use the patternProperties approach. I'm fine with opening an issue in the handbook, and then adding a link from the Extension Explorer once the content is ready.

Regarding users, I think only the Project extension uses this approach for multilingual support (others use it for currency exchange or arbitrary key-value pairs, like a metric's dimensions), so I don't think we need to add anything for users here.

• Add content relevant to passing extension review (see internal process document)
• Consider which of the review criteria to add to the readmes of the extension registry or extension template

I've integrated the criteria from the 'quick checks' section of the process note, but left the 'in-depth checks'. Potentially, we could add the criteria under the 'individual files' subheading to the extension registry readme.

I'm not sure which heading you're referring to. Do you mean under each subheading under this heading in the template's repo? https://github.com/open-contracting/standard_extension_template#extension-repository-structure

• Decide whether to move content from the extension template to either the explorer or the standard documentation

  • This content might be split into multiple pages.
  • If moved, we can replace the extension template readme with sample headings and expand on what makes good documentation

There's a lot to integrate here and I don't think the current location is causing any problems, so I suggest we keep it as-is and open a follow-up issue on integrating it (if there is a need/demand). Does that sound good?

Sounds good. Note that there is this other issue about moving just one section of the template out: open-contracting/standard_extension_template#37

• Make sure https://www.open-contracting.org/2018/01/30/fields-dont-map-first/ is integrated

The guidance in this blog is more about the process for mapping additional fields than it is about using or creating extensions. I think it would fit better under https://standard.open-contracting.org/latest/en/guidance/map/#consider-using-extensions, The information that is not repeated elsewhere can be boiled down to:

Before using extensions, you should decide whether the additional data that you want to disclose affects how users should interpret fields in the OCDS schema. If so, consider whether you can include extra information in an existing field to alert users who only know about fields in the OCDS schema. For example, to disclose data about the disposal of state assets, in addition to using an extension, you can prefix tender.title with 'Disposal:'.
You should also double-check whether the additional data that you want to disclose can be modelled using an existing field. For example, to disclose the date by which the procuring entity will respond to enquiries, rather than adding a field, you can use tender.milestones.

What do you think?

True - sounds good to me to integrate those points.

• Make sure https://www.open-contracting.org/2018/07/16/creating-managing-ocds-extensions/ is integrated

Once the Extension Explorer is updated, we should add a note to this blog to direct readers to the updated guidance.

👍

[duncandewhurst]

I've integrated the content in #67. I did this by copy-pasting the content from the Google Doc and then adding the HTML tags. Let me know if there is an easier way - the output from Google's HTML export was a mess. I chose to split the publisher and user guidance into separate pages since they serve different audiences.

I've opened an issue to add guidance on multi-lingual support to the handbook: open-contracting/standard-development-handbook#250

I've opened an issue about moving content from the standard extension template: open-contracting/standard_extension_template#41

I've integrated the content from https://www.open-contracting.org/2018/01/30/fields-dont-map-first/ in open-contracting/standard#1428

• Add content relevant to passing extension review (see internal process document)
• Consider which of the review criteria to add to the readmes of the extension registry or extension template

I've integrated the criteria from the 'quick checks' section of the process note, but left the 'in-depth checks'. Potentially, we could add the criteria under the 'individual files' subheading to the extension registry readme.

I'm not sure which heading you're referring to. Do you mean under each subheading under this heading in the template's repo? https://github.com/open-contracting/standard_extension_template#extension-repository-structure

Ah sorry, I was referring to the headings in the process note. I've integrated the quick checks, but left the in depth checks. My suggestion was to add the content from the individual files subheading to the extension registry readme - I hadn't thought about where exactly in the readme to put it, though.

[jpmckinney]

Right - I don't think it belongs in the registry repo, if the goal is for publishers to author good quality extensions (whether registered or not). I thought maybe it'd work better in the extension template repo (though if we move content out of there, then it probably makes sense to put it in the Extension Explorer). At any rate, can you create a follow-up issue?

[duncandewhurst]

Done!

[jpmckinney]

Aha, the deployment build error reminded what I meant about multilingual support.

If the Extension Explorer identifies that a field has multilingual support, it says so ("This field has multilingual support."). I'll link to https://standard.open-contracting.org/latest/en/schema/reference/#language.