Update structure of standard presentation

[practicalparticipation]

We should consider the best way to present all the relevant information on the site, including (suggestions for discussion):

• Making use of a left-hand scrollspy menu to link people to relevant bits of the current page.
• Breaking out a 'Full Schema' and 'Step by Step' presentation of the standard.
• In the Step by Step presentation having a tab for each of the elements of the release, along with clear friendly narrative text
• Providing various example data in these sections, presented in multiple formats (as Popolo does here)
• Including clear links to the validator on the site

I suspect this would benefit from some brief wireframing before implementation.

[practicalparticipation]

Further notes on Information Architecture:

• Users will generally want to start from records and work back to releases in more specific use caes
• We should encourage publishers to start from reading about releases and to work up to reading about records

[practicalparticipation]

I would suggest updating the site to have at least five distinct pages with their own URLs (rather than the current use of tabs to load page contents) and with these including:

• Home
• Reference documentation
• Schema
• Publishing data (optional, could fit in ref docs.)
• Data users (optional, could fit in ref docs in initial version.)
• Tools
• About

More detail on each page is provided below.

Home

Containing a short, clear overview of the standard, followed by two sets of simple 'calls to action' for publishers and users. (Modeled on the GTFS 'How Do I Start?' section).

Calls to action might include:

For publishers:

• Read more about the origin, goals & development of the standard -> Linking to 'about' pages
• Review the check-list for data creators -> Linking to a section of 'publishing data'
• Publish your own data using the schema reference and publication guidance - > Lining to 'reference documentation' and 'publishing data'
• Test your data with the validation tools -> Linking to 'tools'
• Publish your data & let us know about it -> Linking to 'publishing data'

For users

• Read more about the origin, goals & development of the standard -> Linking to 'about' pages
• Explore different use cases for the standard -> Linking to 'data users'
• Understand how to process data using the schema -> Linking to 'reference documentation'
• Find tools and tips for dealing with data -> Linking to 'tools'

Reference Documentation

A large page, with detailed left-hand menu, breaking down the standard into sections and providing narrative, schema extracts and examples for each.

• Walkthrough
  • Contracting process
  • OCID
  • Releases
  • Release header
  • Release types
  • Planning
  • Tender
  • Award
  • Contract
  • Performance
  • Multilingualism
  • Organisation identifiers
  • Documents
  • Records
  • Merging
  • Validation
  • Alternative serialisation
  • Publication

This may require the extracts from the schema and examples to be rendered as part of the page HTML, rather than imported via javascript, in order that the page load is guaranteed (I sometimes get errors with the javascript blocks not loading properly). Some thought to ensuring the examples are updated along with schema updates will be needed.

Schema

The current schema tabs, and links to download the schema files.

Publishing Data

Including a publishers checklist and the detailed guidance on using /.well-known/ or other selected approaches to make data discoverable.

Addressing issues such as:

• Listings of available data (atom feeds?)
• Content/language negotiation
• Providing data dumps
• Segmentation of data dumps

Data users

A page showing the primary use cases the standard is built around, and the features demanded by these use-cases.

Our primary use cases are:

• Detecting corruption and fraud in public contracting;
• Achieving value for money for public agencies;
• Enabling the private sector to compete fairly for public contracts; and
• Monitoring aid or budget execution for effectiveness;

For each use case we will have:

• A brief description (2 - 3 lines)
• A list of requirements
• (In future) a set of tests that can be run through the validator to see if data is up-to-scratch

Tools

A page describing the various tools that exist to assist in generating data.

• mapper
• compiler
• validator

With descriptions of each, and links off to relevant support information

About

Setting out:

• Goals of the standard
• Development process (including details of the team involved)
• Governance
• Roadmap

[birdsarah]

Just fyi, it may well be easier to start with a fresh codebase / orphan branch and copy and paste the useful bits of what i have rather than re-working what's here. not sure, up to devs, but i won't be offended.

in particular, we may also want/need to overhaul the standard repo which currently has one .md page for each section. i still think this is quite effective, but there's a real challenge when combining with snippets from the schema.

i think the best way around this would be to write a custom markdown parser element so that we could easily inject pieces of the standard and not use docson (at least not the way we currently do).