Consider whether to move content from the readme to either the Extension Explorer or the standard documentation

[duncandewhurst]

From https://github.com/open-contracting/extension-explorer/issues/47

In addition to https://github.com/open-contracting/standard_extension_template/issues/37, we should consider whether to move the other content.

Once done, we might need to update the content in the Extension Explorer that refers to this template.

[jpmckinney]

More detail from the linked issue:

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.

I think the last point might be a good motivation to move the content, as most third-party readmes are low quality.

[duncandewhurst]

I agree that it makes sense to move everything but Getting started to the extension explorer documentation.

I've prepared a draft update to the publisher guidance to do that.

@jpmckinney do you want to review the draft before I update the HTML templates in https://github.com/open-contracting/extension-explorer/pull/84? I've saved a comparison so that you can see what changed.

[duncandewhurst]

@jpmckinney in the interest of keeping things moving, shall I go ahead with updating the HTML templates and then you can review the content as part of the PR?

[jpmckinney]

I accepted "format" suggestions just to make the comparison easier to read. I made direct edits to the draft update. To keep things moving, I added comments where the motivation for my edits might be unclear, and then resolved them.

I'm now done my edits so this is ready for PR.

[jpmckinney]

If moved, we can replace the extension template readme with sample headings and expand on what makes good documentation.

I think the last point might be a good motivation to move the content, as most third-party readmes are low quality.

I created a new issue for this: #53

[jpmckinney]

Actually, I had an idea to simplify the guidance – I'll do that tomorrow, then it'll be ready for PR.

[jpmckinney]

Ok, I made my changes, described below. Now ready.

---

My idea was to move more of the page content into the schema and template, in particular for the metadata file.

I found a schema viewer/editor that does a good job: https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2Fopen-contracting%2Fstandard-maintenance-scripts%2Frefs%2Fheads%2Fmain%2Fschema%2Fextension-schema.json

I removed the content about multilingual fields. They are essentially deprecated. For the Extension Explorer, we use Babel to extract strings from extension.json and then translate them with gettext. Other publishers have generally not used the multilingual support (and where they have, it is more because they were following instructions, rather than because they were serving a use case).

[duncandewhurst]

Your changes look good to me. Thanks for explaining your motivations.

Regarding your comments on the sentences from the standard extension template about using JSON Merge Patch and editing the schema to add new fields: Whilst I agree that it's more direct to write new fields in a new file (that is what I do), I think the intention was probably to help first-time extension creators to avoid mistakes in nesting new fields. FWIW, there's now a web tool alternative to the command-line process described in the previous draft, but it's probably a bit lengthy to explain how/where to paste in the OCDS schema.

[jpmckinney]

Yes, nesting is a common problem (e.g. missing properties), though I think there is only one extension in use that currently has this issue.

@yolile What have you seen, in terms of demand from publishers for support around authoring extensions? We can add more content/tools, but I want to have a better idea of what will be helpful.

[yolile]

@yolile What have you seen, in terms of demand from publishers for support around authoring extensions?

cc @ndrhzn @fppenna as they have been supporting partners in authoring extensions recently. We could also ask Tony if needed.

In my past experience, our support was focused on defining the fields and structure together with the partner, and then us sharing how the schema would look like and asking them to fill out the documentation part (README, fields definition). We also have some cases where more advanced or autonomous partners authored the extensions themselves and did it right (at least the repo and schema structure were right) but I'm not sure what tools they've used.

[jpmckinney]

@yolile @fppenna @ndrhzn If you have any suggested improvements for https://extensions.open-contracting.org/en/publishers/ (see last few comments here for context), please comment here.

[yolile]

I've reviewed the content while translating it and it seems quite straightforward, clear, and complete now, so no suggestions from my side :)

[fppenna]

Similar to what YL mentioned, I supported partners in defining the fields and structure. They took care of defining the schema and completing the documentation.