Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better Guidance/Map/*/Mapping the hard cases structure #1333

Closed
JachymHercher opened this issue Jul 14, 2021 · 1 comment · Fixed by #1338
Closed

Better Guidance/Map/*/Mapping the hard cases structure #1333

JachymHercher opened this issue Jul 14, 2021 · 1 comment · Fixed by #1338
Assignees
Labels
Focus - Documentation Includes corrections, clarifications, new guidance, and UI/UX issues

Comments

@JachymHercher
Copy link
Contributor

The introduction of the planning process and changes in the definitions of the contracting process (#866), contracts (#896), awards (#895) as well as the stages of the contracting process (#1160) require changes in the documentation. Since Getting Started is and will be very general, the place to do this is the Guidance, specifically Mapping the hard cases.

Looking at the Guidance, I think this might be easier to do if we first "streamline" the Guidance with the current content and only as a second step stard updating it with new content. Here are my proposals on improving the structure of the hard cases, which follows up on the proposed improvements to the guidance/map section in general (#1300)

The points below describe the bigger changes, the smaller ones I suggest we discuss over the actual PR.

  1. Currently, the hard cases are listed alphabetically. I would propose ordering them into three thematic sections: cases linked to the contracting processes as a whole; to parts of the process; to organizations. Within each section, the cases should be structured by logical dependency (e.g. contracts before amendments) or by popularity (e.g. organisation classifications before beneficial ownership). I this will make it easier to navigate for users and it also corresponds to what I assume is the more typical use case for readers, i.e. reading through all (or almost all) of them when working on the mapping, not just going through a few selected cases.

The resulting structure is at the bottom of this post.

  1. Rename "Unsuccessful tenders" to "Contracting process".

  2. Restructure "Awards, contracts, buyers and suppliers".

    • i) Split it into "Awards and contracts" and "Buyers and suppliers", as the section currently unnecessarily discusses too many things at once.
    • ii) Remove parts that are not particularly helpful (e.g. the UNCITRAL definitions).
    • iii) Move "electronic catalogues" into a separate section, because the (very little) content is essentially independent of anything else. We could consider removing it altogether, but keeping it there (easily findable) just to answer the FAQ "and what about electronic catalogues?" is maybe not a bad idea.
    • iv) Remove the anomaly (for this level of nesting) that examples ("Award and contracts" etc.) are listed in separate webpages. This can be done by merging "Consortia suppliers" with "Buyers and suppliers"; removing the link to "Framework Agreements and Related Processes" (it is a self-standing page on the same level as "Awards, contracts, buyers and suppliers"), merging the remaining examples into the core text. The resulting page has 200 rows, which is not out of line with other pages (Framework Agreements have 300 rows, Amendments and Milestones 150 rows each).
    • v) Rename "Award notices and decisions" to "Award notices and awards (as that it what it is).
    • vi) ("Purchase orders" should be changed as well, but I would do that when updating the section on the basis of Clarify Contract description #896).
  3. Consistently have uppercase only at the beginning of each heading.


Resulting structure:

map/contracting_process
map/related_processes
map/pre-qualification
map/awards_contracts
map/electronic_catalogues
map/amendments
map/milestones
map/buyers_suppliers
map/organization_reference
map/organization_identifiers
map/organization_personal_identifiers
map/organizational_units
map/organization_classifications
map/beneficial_ownership

@JachymHercher JachymHercher added the Focus - Documentation Includes corrections, clarifications, new guidance, and UI/UX issues label Jul 14, 2021
@JachymHercher JachymHercher changed the title Better Guidance/Map/"Hard Cases" structure and content Better Guidance/Map/Mapping your data to OCDS/Mapping the hard cases structure and content Jul 14, 2021
@JachymHercher JachymHercher changed the title Better Guidance/Map/Mapping your data to OCDS/Mapping the hard cases structure and content Better Guidance/Map/Mapping the hard cases structure and content Jul 14, 2021
@JachymHercher JachymHercher changed the title Better Guidance/Map/Mapping the hard cases structure and content Better Guidance/Map/*/Mapping the hard cases structure and content Jul 14, 2021
@JachymHercher JachymHercher changed the title Better Guidance/Map/*/Mapping the hard cases structure and content Better Guidance/Map/*/Mapping the hard cases structure Jul 14, 2021
@JachymHercher JachymHercher linked a pull request Jul 14, 2021 that will close this issue
@jpmckinney
Copy link
Member

As discussed on our call, I agree with the proposed changes. In a later PR, we will revisit unsuccessful tenders, as it spends too much time describing a contracting process, which should probably be explained elsewhere (not in a worked example).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Focus - Documentation Includes corrections, clarifications, new guidance, and UI/UX issues
Projects
None yet
2 participants