diff --git a/.github/workflows/spell_checker.yml b/.github/workflows/spell_checker.yml new file mode 100644 index 0000000..439c209 --- /dev/null +++ b/.github/workflows/spell_checker.yml @@ -0,0 +1,12 @@ +name: Spellcheck Action +on: [push, pull_request] + +jobs: + build: + name: Spellcheck + runs-on: ubuntu-latest + steps: + # The checkout step + - uses: actions/checkout@v3 + - uses: rojopolis/spellcheck-github-actions@v0 + name: Spellcheck diff --git a/.spellcheck.yml b/.spellcheck.yml new file mode 100644 index 0000000..d658cd2 --- /dev/null +++ b/.spellcheck.yml @@ -0,0 +1,21 @@ +matrix: +- name: Markdown + aspell: + lang: en + d: en_GB + dictionary: + wordlists: + - .wordlist.txt + output: wordlist.dic + encoding: utf-8 + pipeline: + - pyspelling.filters.url: + - pyspelling.filters.markdown: + - pyspelling.filters.html: + comments: false + ignores: + - code + - pre + sources: + - 'docs/**/*.md' + default_encoding: utf-8 diff --git a/.wordlist.txt b/.wordlist.txt new file mode 100644 index 0000000..08a97ce --- /dev/null +++ b/.wordlist.txt @@ -0,0 +1,77 @@ +Airtable +APIs +bestValueToGovernment +Bytemark +Changelog +changelog +changelogs +codelist +codelists +COH +contratación +CoVE +CRM +CSV +Deprioritisation +dev +DoNotTrack +dropdown +eval +funders +GDPR +GeoJSON +GitHub +grantmakers +GrantNav +helpdesk +Helpdesk +Holyoake +howto +hypothes +IATI +ICO +IETF +ILDA +implementers +incentivise +io +json +licitación +LinkedIn +Matomo +maxdepth +multilingually +NGOs +OCDS +oferta +ontologies +opendataservices +Parsers +po +pre +programmatically +propuesta +pseudonymised +ratedCriteria +readthedocs +recommonmark +RedmineUp +reproducibility +reStructuredText +roadmap +rst +rulesets +schema's +schemas +seealso +SSOT +symlink +toctree +Transifex +USD +validator +validators +VLOOKUP +Wardley's +XLS +XLSX diff --git a/docs/about/index.md b/docs/about/index.md index 944b232..317bcbc 100644 --- a/docs/about/index.md +++ b/docs/about/index.md @@ -2,7 +2,7 @@ Open Data Services Co-operative was established in 2015 to support organisations to publish and use open data. We have a particular focus on incubating early stage open data standards, and supporting the development of effective transparency and collaboration initiatives using well-maintained open data standards. -We often act as the technical partner to policy-focussed initiatives, working under contract to develop and maintain open data standards, and to support standard implementation. +We often act as the technical partner to policy-focused initiatives, working under contract to develop and maintain open data standards, and to support standard implementation. Our team of employees and members work across a range of tasks: diff --git a/docs/components/advocacy_plan.md b/docs/components/advocacy_plan.md index 3b46318..4c27436 100644 --- a/docs/components/advocacy_plan.md +++ b/docs/components/advocacy_plan.md @@ -2,7 +2,7 @@ ## Summary -Setting out steps to encourage organizations to adopt the standard. +Setting out steps to encourage organisations to adopt the standard. ## Description diff --git a/docs/components/commitment_templates.md b/docs/components/commitment_templates.md index 5003aff..dea6c86 100644 --- a/docs/components/commitment_templates.md +++ b/docs/components/commitment_templates.md @@ -11,7 +11,7 @@ Draft commitments are templates for adopters to copy or adapt before signing and ## Prioritisation Factors - If a standard requires a relatively high level of commitment to be useful -- If a standard is targetting public sector organisations that are keen to formally launch commitments +- If a standard is targeting public sector organisations that are keen to formally launch commitments - If a very early-stage standard requires commitment in principle before development begins diff --git a/docs/components/communication_channels.md b/docs/components/communication_channels.md index 69b84db..2317e28 100644 --- a/docs/components/communication_channels.md +++ b/docs/components/communication_channels.md @@ -9,9 +9,9 @@ Used to communicate with implementers, users and other stakeholders. Different communication channels suit different audiences and content types, for example: * A *blog* that is regularly updated can provide updates to the community, resources for them to refer back to, and act as a 'shop window' for the standard, demonstrating that it is maintained and used. -* Public *social media channels* such as a LinkedIn page allow a standard to communicate little and often, and to engage with their communities in a relateable way. Some open communities already have a strong presence on microblogging sites, so the friction for engagement is reduced. +* Public *social media channels* such as a LinkedIn page allow a standard to communicate little and often, and to engage with their communities in a relatable way. Some open communities already have a strong presence on social media sites, so the friction for engagement is reduced. -* An *email list* is a widely-accessible and low-cost way for a group to hold discussions, and many email list providers offer a public archive service so that accountability is maintained. Standards often have a discussion list and a separate announcement list, so that members can choose how involved they want to be. The asynchronous nature of email lists allows users to be involved as regularly or infrequently as they prefer. However, some users are reticent to post to public email lists for fear of appearing foolish or having their words during their learning being recorded. +* An *email list* is a widely accessible and low-cost way for a group to hold discussions, and many email list providers offer a public archive service so that accountability is maintained. Standards often have a discussion list and a separate announcement list, so that members can choose how involved they want to be. The asynchronous nature of email lists allows users to be involved as regularly or infrequently as they prefer. However, some users are reticent to post to public email lists for fear of appearing foolish or having their words during their learning being recorded. ## Prioritisation factors @@ -26,4 +26,4 @@ Different communication channels suit different audiences and content types, for * Blogs: If there isn't the resource available to make regular updates. * Social media: If the time, people or infrastructure required to make regular updates is not available -* Email lists: If there is reticence among users about public email lists \ No newline at end of file +* Email lists: If there is reticence among users about public email lists diff --git a/docs/components/communications_plan.md b/docs/components/communications_plan.md index 024c8e7..2ccdc4c 100644 --- a/docs/components/communications_plan.md +++ b/docs/components/communications_plan.md @@ -6,7 +6,7 @@ Setting out steps to get media coverage of the standard. ## Description -A communications plan sets out the steps that are planned to encourage media coverage of the standard. Having a plan ensures that media opportunities are sought, and that representatives of the standard are well-equipped when taking advantage of opportunities. It can ensure that the standard is properly represented, setting expectations among potential users and beneficaries. +A communications plan sets out the steps that are planned to encourage media coverage of the standard. Having a plan ensures that media opportunities are sought, and that representatives of the standard are well-equipped when taking advantage of opportunities. It can ensure that the standard is properly represented, setting expectations among potential users and beneficiaries. ## Prioritisation Factors diff --git a/docs/components/conversion_tools.md b/docs/components/conversion_tools.md index 2268f91..fdc8b31 100644 --- a/docs/components/conversion_tools.md +++ b/docs/components/conversion_tools.md @@ -2,11 +2,11 @@ ## Summary -Allowing conversion between serialization formats (e.g. CSV -> XML; JSON -> XLS) +Allowing conversion between serialisation formats (e.g. CSV -> XML; JSON -> XLS) ## Description -Data standards often use structured data formats such as JSON or XML to give more flexbility in modelling and to allow validation against schema. Typically, developers prefer to work with structured data formats as they are easier to work with in programs. However, JSON and XML aren't very human-friendly, and people working with data in many domains prefer to use flat representations of data such as CSV and XLSX spreadsheets, both for publishing and manipulating data. Conversion tools allow conversion between the formats, to allow the standard and developers to retain the benfits of a structured data format and users to continue to be able to engage with the data in a way that they're comfortable with. +Data standards often use structured data formats such as JSON or XML to give more flexibility in modelling and to allow validation against schema. Typically, developers prefer to work with structured data formats as they are easier to work with in programs. However, JSON and XML aren't very human-friendly, and people working with data in many domains prefer to use flat representations of data such as CSV and XLSX spreadsheets, both for publishing and manipulating data. Conversion tools allow conversion between the formats, to allow the standard and developers to retain the benefits of a structured data format and users to continue to be able to engage with the data in a way that they're comfortable with. ## Examples diff --git a/docs/components/demonstration_applications.md b/docs/components/demonstration_applications.md index e806c0c..d50ca13 100644 --- a/docs/components/demonstration_applications.md +++ b/docs/components/demonstration_applications.md @@ -6,7 +6,7 @@ Showcasing what can be done with data when it is published to a standard ## Description -Demonstration applications are either real-world or contrived applications using standardised data to illustrate what the data could be used for. They can be used to demonstrate the advantages of using the standard at all, or using particular parts of the stardard. +Demonstration applications are either real-world or contrived applications using standardised data to illustrate what the data could be used for. They can be used to demonstrate the advantages of using the standard at all, or using particular parts of the standard. ## Prioritisation Factors diff --git a/docs/components/developer_guidelines.md b/docs/components/developer_guidelines.md index 2a972c5..13c6bba 100644 --- a/docs/components/developer_guidelines.md +++ b/docs/components/developer_guidelines.md @@ -6,7 +6,7 @@ Describing the coding practices and workflows for contributing to the standard o ## Description -Developer guidelines set out the expectactions of external contributions to the standard or the tools that are provided to support adopters. They typically cover licensing, procedure for contributions to be reviewed, expectations around process, and technical expectations such as comments, naming conventions, tests and coding style. +Developer guidelines set out the expectations of external contributions to the standard or the tools that are provided to support adopters. They typically cover licensing, procedure for contributions to be reviewed, expectations around process, and technical expectations such as comments, naming conventions, tests and coding style. ## Prioritisation Factors diff --git a/docs/components/example_data.md b/docs/components/example_data.md index 27d5a19..87e6287 100644 --- a/docs/components/example_data.md +++ b/docs/components/example_data.md @@ -11,7 +11,7 @@ Adopters of the standard and users of the data are often helped by seeing exampl ## Prioritisation Factors - If the standard is large or complicated -- If adopters or users are often misunderstanding the requirements of the standard or strugging to 'get it' +- If adopters or users are often misunderstanding the requirements of the standard or struggling to 'get it' ## Deprioritisation Factors diff --git a/docs/components/getting_started_documentation.md b/docs/components/getting_started_documentation.md index 2a9e6ec..981461e 100644 --- a/docs/components/getting_started_documentation.md +++ b/docs/components/getting_started_documentation.md @@ -6,7 +6,7 @@ User-friendly and filled with examples. ## Description -The normative documentation for standards is technical, prescise, authoratitive and comprehensive. While this is useful for a reference, the process of learning about a new standard is helped by the same kind of learning resources as any other learning process, including worked examples, guided learning through the standard, and practice materials. +The normative documentation for standards is technical, precise, authoritative and comprehensive. While this is useful for a reference, the process of learning about a new standard is helped by the same kind of learning resources as any other learning process, including worked examples, guided learning through the standard, and practice materials. ## Prioritisation Factors diff --git a/docs/components/icons.md b/docs/components/icons.md index 1b360c4..2e15177 100644 --- a/docs/components/icons.md +++ b/docs/components/icons.md @@ -10,7 +10,7 @@ Icons help with recall of key concepts, and consistency across a range of assets ## Prioritisation Factors -- If a standard is being discussed across media (eg in print, online and in person) +- If a standard is being discussed across media (e.g. in print, online and in person) - If the standard is being translated - If the standard introduces concepts unfamiliar to typical adopters - If the standard is being discussed across policy and technical boundaries diff --git a/docs/components/index.md b/docs/components/index.md index 6318f39..2d4b3ad 100644 --- a/docs/components/index.md +++ b/docs/components/index.md @@ -2,7 +2,7 @@ On reviewing a range of policy-related data standards, including those that we maintain and those maintained by others, we identified approximately 60 components that at least two standards have chosen to create or adopt. -Whether or not these are important to a particular standard depends on lots of factors, including but not limited to the maturity of the standard, whether the standard’s adoption is being driven co-operatively or adversarially, political factors and the character of the people and organisations in the domain where the standard operates. +Whether or not these are important to a particular standard depends on lots of factors, including but not limited to the maturity of the standard, how the standard's adoption is being driven, political factors and the character of the people and organisations in the domain where the standard operates. We conducted an exercise with representatives of several standards, asking them to conduct a diamond ranking exercise of the components. Diamond ranking was chosen to allow a ‘fat middle’ while forcing a decision on the highest and lowest priority items. Participants were asked to consider a standard at different levels of maturity, using Charles Handy’s Second Curve model for describing maturity. @@ -89,4 +89,4 @@ glob: hidden: --- * -``` \ No newline at end of file +``` diff --git a/docs/components/logo.md b/docs/components/logo.md index b66e90f..ad461b4 100644 --- a/docs/components/logo.md +++ b/docs/components/logo.md @@ -6,7 +6,7 @@ A logo for the standard ## Description -A logo helps to reinforce the brand of the standard, gives a visual cue for recognition in resources, and can be used (with permission) by adoptors to demonstrate their use of the standard +A logo helps to reinforce the brand of the standard, gives a visual cue for recognition in resources, and can be used (with permission) by adopters to demonstrate their use of the standard ## Prioritisation Factors diff --git a/docs/components/recommended_data_license.md b/docs/components/recommended_data_license.md index fa47a00..82093c4 100644 --- a/docs/components/recommended_data_license.md +++ b/docs/components/recommended_data_license.md @@ -6,7 +6,7 @@ E.g. the requirement that publishers should use Creative Commons or Open Databas ## Description -A recommended license can help to ensure that adopters give due consideration to licensing, as well as setting a high bar for adopters and encouraging intertia among the community using the standard. +A recommended license can help to ensure that adopters give due consideration to licensing. Clearly and openly licensed data encourages data use by the wider community. ## Prioritisation Factors diff --git a/docs/components/reference_lists.md b/docs/components/reference_lists.md index 3618e07..d740160 100644 --- a/docs/components/reference_lists.md +++ b/docs/components/reference_lists.md @@ -2,6 +2,6 @@ ## Summary -Lookup lists for key concepts (e.g. organization registers). +Lookup lists for key concepts (e.g. organisation registers). diff --git a/docs/components/spreadsheet_template.md b/docs/components/spreadsheet_template.md index 6ff3ba4..b46a220 100644 --- a/docs/components/spreadsheet_template.md +++ b/docs/components/spreadsheet_template.md @@ -2,6 +2,6 @@ ## Summary -An editorialised template that can be filled in to provide data that meets the standard (Excel / AirTable etc.) +An editorialised template that can be filled in to provide data that meets the standard (Excel / Airtable etc.) diff --git a/docs/components/validator.md b/docs/components/validator.md index f14f61b..9d4dda6 100644 --- a/docs/components/validator.md +++ b/docs/components/validator.md @@ -10,7 +10,7 @@ For more information about how schema validation relates to additional checks, s ## Prioritisation Factors -* Specific error reporting and user expreience: If implementers need context-specific error messages and guidance, target feedback or multiple output formats (e.g. human-readable reports and machine-readable JSON for integration with other tools). +* Specific error reporting and user experience: If implementers need context-specific error messages and guidance, target feedback or multiple output formats (e.g. human-readable reports and machine-readable JSON for integration with other tools). * Complexity beyond the schema language: If the standard involves additional rules that cannot be expressed in its schema language, validation of codelists specified outside the schema, or semantic validation of the data beyond its structure and format. ## Deprioritisation Factors @@ -33,4 +33,4 @@ The Open Contracting Data Standard (OCDS) provides a web-based validator (the [O ## Related patterns -* [Permissive schema](../patterns/schema.md#permissive-schema) \ No newline at end of file +* [Permissive schema](../patterns/schema.md#permissive-schema) diff --git a/docs/development/documentation.md b/docs/development/documentation.md index a0482c3..404d257 100644 --- a/docs/development/documentation.md +++ b/docs/development/documentation.md @@ -18,7 +18,7 @@ Sphinx has the ability to process and integrate documentation from different sou We have created a number of [custom directives documented here](https://github.com/OpenDataServices/sphinxcontrib-opendataservices). -[reStructuredText](http://docutils.sourceforge.net/rst.html) is the native input format for Sphinx builds. However, with the bridge library recommommark, it is possible to use input files in Markdown. +[reStructuredText](http://docutils.sourceforge.net/rst.html) is the native input format for Sphinx builds. However, with the bridge library [recommonmark](https://recommonmark.readthedocs.io/en/latest/index.html), it is possible to use input files in Markdown. We maintain a custom [sphinx-base](https://github.com/OpenDataServices/sphinx-base) project to use when starting new documentation sites. diff --git a/docs/development/getting-started.md b/docs/development/getting-started.md index f221513..ee5118e 100644 --- a/docs/development/getting-started.md +++ b/docs/development/getting-started.md @@ -20,9 +20,9 @@ We think of effective open data standards as tools of **mass collaboration**, pr The International Aid Transparency Initiative (IATI) standard promotes interoperability of aid data, through alignment of both the structure and the contents of descriptions of aid activities. - A growing range of tools now exist that create and use IATI data, including tools to visualize spending flows, platforms to search and explore projects and their associated documents, and services to analyze foreign exchange risks that projects are exposed to. + A growing range of tools now exist that create and use IATI data, including tools to visualise spending flows, platforms to search and explore projects and their associated documents, and services to analyse foreign exchange risks that projects are exposed to. - Across the 600+ organizations publishing data using the IATI Standard, there are active participants who publish and use data, and more passive participants who just share data in response to administrative rules from their funders. + Across the 600+ organisations publishing data using the IATI Standard, there are active participants who publish and use data, and more passive participants who just share data in response to administrative rules from their funders. ``` @@ -38,11 +38,11 @@ Without a standard, users or intermediaries have to do the hard work of making s By contrast, a standard with strict validation rules places a heavy burden on data owners to restructure their systems in order to produce valid and conforming data. -In some cases, it may be quicker or cheaper in the short-term to invest in intermediaries or centralized databases that can reconcile data from different sources. However, this can risk creating a single point of failure or a point of control, which is avoided if data owners take responsibility for publishing their own data using an open standard. +In some cases, it may be quicker or cheaper in the short-term to invest in intermediaries or centralised databases that can reconcile data from different sources. However, this can risk creating a single point of failure or a point of control, which is avoided if data owners take responsibility for publishing their own data using an open standard. By contrast, whilst it might initially be trickier to encourage adoption of distributed standards for data publication, a well-functioning ecosystem of data publishers, intermediaries and users can be more resilient and innovative in the long-run. -Recognizing these trade-offs is important when designing a data standards project. +Recognising these trade-offs is important when designing a data standards project. ## Questions to answer @@ -66,7 +66,7 @@ Some of the roles include: - **Project lead** - maintaining relationships and communication with different stakeholders, and the balance between supply-side and demand-side considerations in the development of a standard. - **User researcher** - facilitating dialogue with potential users of published data, and with data owners, to understand, document and champion their needs. -- **Data analyst** - reviewing pre-standard data to identify opportunities for standardisation, and analysing draft and published data for quality assurance and learning. +- **Data analyst** - reviewing current data to identify opportunities for standardisation, and analysing draft and published data for quality assurance and learning. - **Standard architect** - designing the overall shape of the standard, establishing data structures, selecting schema languages, data patterns, validation and quality evaluation approaches, and identifying tools required alongside the standard. - **Schema author** - translating agreed data structures and fields into a schema language, and coordinating work to define fields and relationships. Also working on standard extensions where applicable. - **Documentation author** - writing technical and user-focused documentation, creating worked examples, and developing training resources. @@ -75,7 +75,7 @@ Some of the roles include: - **Translation manager & translators** - creating glossaries, arranging translation, and carrying out translations. - **Governance lead** - coordinating the process of standard updates. - **Community manager(s)** - engaging with technical and policy communities, supporting tool-building, documenting implementation case studies, ensuring community input into standard development. -- **Implementation and helpdesk manager** - making sure implementers have their queries addressed promptly, monitoring the quality of implementation and focussing on health of the overall ecosystem of data sharing and use. +- **Implementation and helpdesk manager** - making sure implementers have their queries addressed promptly, monitoring the quality of implementation and focusing on health of the overall ecosystem of data sharing and use. - **Helpdesk analysts** - providing training and support to implementers and users, performing data quality assurance. In our experience, standard development benefits from creative tension between team members playing different roles. For example, getting the right balance between simply usability of a dataset, and the accuracy and nuance of the data, will benefit from open discussion and negotiation between team members, each acting as a champion of different points of view. @@ -84,7 +84,7 @@ In our experience, standard development benefits from creative tension between t --- class: hint --- -The Open Data Services team work in partnership with a range of organizations to deliver or support many of the roles above. +The Open Data Services team work in partnership with a range of organisations to deliver or support many of the roles above. Get in touch to find out how we could help you: [our services](http://www.opendataservices.coop/#services). diff --git a/docs/development/governance.md b/docs/development/governance.md index d64aadf..ebe970e 100644 --- a/docs/development/governance.md +++ b/docs/development/governance.md @@ -16,7 +16,7 @@ The governance process for the Open Contracting Data Standard is set out in the ![Governance process](https://standard.open-contracting.org/latest/en/_images/upgrade_process.png) -As the OCDS [ChangeLog illustrates](http://standard.open-contracting.org/latest/en/schema/changelog/), each change has a related GitHub issue where changes are discussed. +As the [OCDS changelog](http://standard.open-contracting.org/latest/en/schema/changelog/) illustrates, each change has a related GitHub issue where changes are discussed. During the revision process, discussions took place in a range of fora, including through the mailing list, at face-to-face events, or through webinars. However, substantive points should always be written up as part of the GitHub issues to ensure changes are documented and justified. diff --git a/docs/development/index.md b/docs/development/index.md index 1a6455e..1757bae 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -2,15 +2,15 @@ This handbook is about policy-related open data standards. These cover both **content** (what to publish) and **representation** (how to publish). -The handbook describes maintaining data specifications that can support the realization of policy goals. +The handbook describes maintaining data specifications that can support the realisation of policy goals. ```{admonition} Example --- class: note --- -A campaign calls for organizations to publish their pay ratios between men and women, and highest and lowest paid employees, in order to highlight and address pay inequality. This is the policy goal. +A campaign calls for organisations to publish their pay ratios between men and women, and highest and lowest paid employees, in order to highlight and address pay inequality. This is the policy goal. -A schema is developed and documented, describing how to publish CSV files on an organization's website that provide these figures. This is the data specification. +A schema is developed and documented, describing how to publish CSV files on an organisation's website that provide these figures. This is the data specification. Further documentation, data-quality frameworks, and validation models are developed that can be used to check that the data provided using the specification is accessible, meaningful and actionable. Together with the specification, this constitutes the open data standard. diff --git a/docs/development/schema.md b/docs/development/schema.md index 6a49dda..c7fa490 100644 --- a/docs/development/schema.md +++ b/docs/development/schema.md @@ -4,11 +4,11 @@ This page provides an overview of the steps involved in data modelling and schem ## Document a data model -A data model is an abstract model that organizes elements of data and standardises how they relate to one another and to the properties of real-world entities. A data model focuses on what data represents rather than how it is stored or exchanged. +A data model is an abstract model that organises elements of data and standardises how they relate to one another and to the properties of real-world entities. A data model focuses on what data represents rather than how it is stored or exchanged. Before authoring the schema for a standard and committing to specific implementation details, it is recommended to document a data model to help stakeholders align on definitions and relationships. -The data model for a standard should be based on [research](research) into the related policy area and a thorough understanding of the concepts which underpin it (a conceptual model). Documenting the data model for a standard involves identifying and defining the entities (classes), attributes (properties), relationships and permissable values (codelists) needed to satisfy the requirements, user stories and use cases for the standard. +The data model for a standard should be based on [research](research) into the related policy area and a thorough understanding of the concepts which underpin it (a conceptual model). Documenting the data model for a standard involves identifying and defining the entities (classes), attributes (properties), relationships and permissible values (codelists) needed to satisfy the requirements, user stories and use cases for the standard. Developing a good data model is an art as much as a science. It requires sensitivity to the needs of both data producers and data users, and an understanding of the incentive structures that will drive adoption of a standard. @@ -41,14 +41,14 @@ Open Data Services' reusable tools for documenting, converting and validating da ```{admonition} Example: The Open Contracting Data Standard :class: note -The primary publication format of the Open Contracting Data Standard is JSON, but CSV and spreadsheet formats are also supported via conversion tooling. For more information, see [Serialization (Open Contracting Data Standard Documentation)](https://standard.open-contracting.org/latest/en/guidance/build/serialization/#serialization). +The primary publication format of the Open Contracting Data Standard is JSON, but CSV and spreadsheet formats are also supported via conversion tooling. For more information, see [Serialisation (Open Contracting Data Standard Documentation)](https://standard.open-contracting.org/latest/en/guidance/build/serialization/#serialization). ``` ```{admonition} Example: 360Giving :class: note -The 360Giving Data Standard supports both spreadsheet and JSON formats, but most 360Giving data is published in spreadsheet format. Therefore, the documentation for the standard is primarily focussed on the spreadsheet format. For more information, see [Choosing your file format (360Giving Data Standard Documentation)](https://standard.threesixtygiving.org/en/latest/guidance/prepare-data/#choosing-your-file-format). +The 360Giving Data Standard supports both spreadsheet and JSON formats, but most 360Giving data is published in spreadsheet format. Therefore, the documentation for the standard is primarily focused on the spreadsheet format. For more information, see [Choosing your file format (360Giving Data Standard Documentation)](https://standard.threesixtygiving.org/en/latest/guidance/prepare-data/#choosing-your-file-format). ``` @@ -72,7 +72,7 @@ If you choose to support other publication formats alongside JSON, you should co ```{admonition} Example: Open Referral :class: note -The canonical schema for the Open Referral Data Specifications is documented using JSON Schema. However, a secondary schema is provided for the Tabular Data Package format, which is derived from the canonical schema. For more information, see [Serialization and Publication Formats (Open Referral Data Specifications Documentation)](http://docs.openreferral.org/en/latest/hsds/serialization.html). +The canonical schema for the Open Referral Data Specifications is documented using JSON Schema. However, a secondary schema is provided for the Tabular Data Package format, which is derived from the canonical schema. For more information, see [Serialisation and Publication Formats (Open Referral Data Specifications Documentation)](http://docs.openreferral.org/en/latest/hsds/serialization.html). ``` @@ -83,7 +83,7 @@ Previously, the recommended approach was to use [JSON Schema Draft 4](https://js ## Choose a codelist format -A codelist defines a set of permissable values for a field. +A codelist defines a set of permissible values for a field. The recommended approach is to document codes, titles and descriptions in a CSV file, according to the [Open Data Services Codelist Schema](https://codelist-schema.readthedocs.io/). @@ -93,9 +93,9 @@ The recommended approach is to document codes, titles and descriptions in a CSV ## Choose your packaging formats -A packaging format is structued way of bundling together data and, sometimes, metadata. You can think of a packaging format as a container for multiple records, texts or documents. +A packaging format is structured way of bundling together data and, sometimes, metadata. You can think of a packaging format as a container for multiple records, texts or documents. -Packaging formats aid interoperability and reuse by providing tool developers and analysts with predicatable and consistent approaches to grouping, streaming and pagination. +Packaging formats aid interoperability and reuse by providing tool developers and analysts with predictable and consistent approaches to grouping, streaming and pagination. Based on your chosen publication formats and the requirements identified in your research, you need to decide on a packaging format or formats for each publication format. @@ -136,4 +136,4 @@ Constraints expressed in a schema are requirements that data must conform to in ```{seealso} * 💡 [Schema patterns](../patterns/schema) * 🧩 [Validator and quality tools](../components/validator) -``` \ No newline at end of file +``` diff --git a/docs/development/stages.md b/docs/development/stages.md index 4dbd783..49fc67e 100644 --- a/docs/development/stages.md +++ b/docs/development/stages.md @@ -4,7 +4,7 @@ The development of a standard should follow a number of stages. It is useful to think of standards development as a diamond-shaped process, each iteration of which begins at a narrowly-defined point, broadens out during the research and development phases and then narrows again as the standard becomes a release-ready product. -In this diamond model, we can identify four distinct phases: starting from a focussed problem; scoping out the original problem and broadening out from it to identify other use-cases and related data; developing the standard to accommodate as many of these use-cases as feasible (which may be far from the full set); and focussing down to a release version. +In this diamond model, we can identify four distinct phases: starting from a focused problem; scoping out the original problem and broadening out from it to identify other use-cases and related data; developing the standard to accommodate as many of these use-cases as feasible (which may be far from the full set); and focusing down to a release version. ```{mermaid} :align: center @@ -18,7 +18,7 @@ graph LR Release"} ``` -Development is an iterative process: going through stages of developing a broad understanding of the problem space that standard addresses, and stages of focussing down to develop concrete data elements and structures that address some aspect of that problem space. +Development is an iterative process: going through stages of developing a broad understanding of the problem space that standard addresses, and stages of focusing down to develop concrete data elements and structures that address some aspect of that problem space. It is important to create artefacts at each stage that stakeholders can engage with and provide feedback on. A development process may go through the following stages: @@ -46,7 +46,7 @@ A conceptual framework or consultation document will set out the rationale for a This document is important to secure agreement on issues such as: - **The primary data element(s) in the standard**. For example, the [conceptual framework draft for the Open Contracting Data Standard](http://standard.open-contracting.org/legacy/r/0__1__0/) established that the primary element would be a 'contracting process', and advanced definitions of other key stages of a process. -- **The target file formats and schema languages**. For example, the [conceptual framework for the Beneficial Ownership Data Standard](https://github.com/openownership/data-standard/issues/7) discusses potential data serializations. +- **The target file formats and schema languages**. For example, the [conceptual framework for the Beneficial Ownership Data Standard](https://github.com/openownership/data-standard/issues/7) discusses potential data serialisations. - **The way data will be shared**. For example, addressing whether the standard will focus on flat files, API exchange of data, or some other approach. ## Alpha diff --git a/docs/development/translation.md b/docs/development/translation.md index 186ddb7..b342b04 100644 --- a/docs/development/translation.md +++ b/docs/development/translation.md @@ -28,7 +28,7 @@ It is important to distinguish a number of concepts: - **Translation** is the process of making a standard and its associated tools and documentation available in more than one language; - **Localisation (l10n)** goes beyond a generic language translation to also consider how a standard and its documentation will be interpreted within a particular local and cultural context. -See also [W3C Localization vs. Internationalization](https://www.w3.org/International/questions/qa-i18n) +See also [W3C Localisation vs. Internationalisation](https://www.w3.org/International/questions/qa-i18n) In general, internationalisation is a task during the development of the [Single Source of Truth (SSOT)](../patterns/documentation.md#single-source-of-truth) for a standard. Translation can take place as part of the core development process, or by supporting community translations, and localisation is a part of implementation support in particular countries and contexts. @@ -78,7 +78,7 @@ Each standard will need to develop its own translation principles. The draft bel 1. **Ensure consistency** by developing a glossary of key terms, and maintaining one glossary per language. The glossary should include definitions, and notes to support translators. -1. **Honouring the work you are asking the reader/user to do** by making sure translations are useable. +1. **Honouring the work you are asking the reader/user to do** by making sure translations are usable. 1. **Engage local reviewers for languages, and work with reviewers with domain expertise** diff --git a/docs/patterns/documentation.md b/docs/patterns/documentation.md index b438325..8ab8b03 100644 --- a/docs/patterns/documentation.md +++ b/docs/patterns/documentation.md @@ -154,7 +154,7 @@ This means that the integrity tests are run, and you can see version of that bra We use two different automated build services, for different projects: -(1) [Read the docs](https://readthedocs.org/) is designed specifically for building Sphinx docs. It will rebuild a version of the documentation every time a commit if pushed to the corresponding branch on GitHub. Read the Docs being designed specifically for Sphinx is useful because it will automatically host the docs, and provides a version/language switcher out of the docs. It gives a lot of control (e.g. you can have whatever custom directives and theming you want, you can point a custom domain at it), but is less flexible than a generic build service. It also requires a manual step to add a new branch/version to the docs. We use Read the Docs for lots of smaller docs sites +(1) [Read the docs](https://readthedocs.org/) is designed specifically for building Sphinx docs. It will rebuild a version of the documentation every time a commit if pushed to the corresponding branch on GitHub. Read the Docs being designed specifically for Sphinx is useful because it will automatically host the docs, and provides a version/language switcher out of the docs. It gives a lot of control (e.g. you can have whatever custom directives and theme you want, you can point a custom domain at it), but is less flexible than a generic build service. It also requires a manual step to add a new branch/version to the docs. We use Read the Docs for lots of smaller docs sites (2) [GitHub Actions](https://github.com/features/actions) - is a generic build service (again building every time something is pushed to GitHub), so requires a bit more setup than Read the Docs, but also gives you maximum flexibility over what commands get run. It can also run tests of the documentation/schema before the build. It doesn’t host docs, but can be set up to push the built docs to a hosting provider of your choice. diff --git a/docs/patterns/translation.md b/docs/patterns/translation.md index 6aabaf9..dcdedcd 100644 --- a/docs/patterns/translation.md +++ b/docs/patterns/translation.md @@ -44,7 +44,7 @@ Provide tools to allow them to comment on the translated text. ### Method -Tools like hypothes.is can support non-technical users (who wouldn't use GitHub) to annotate a schema. +Tools like Hypothesis can support non-technical users (who wouldn't use GitHub) to annotate a schema. --- diff --git a/docs/privacy-notice.md b/docs/privacy-notice.md index 7b2fec9..d4b615e 100644 --- a/docs/privacy-notice.md +++ b/docs/privacy-notice.md @@ -2,7 +2,7 @@ Open Data Services Co-operative Limited is committed to ensuring that your privacy is protected. This privacy notice sets out how we collect and process any personal data when you use this website. -We may change this notice from time to time by updating this page. This notice is effective from 24th May 2018. +We may change this notice from time to time by updating this page. This notice is effective from 24/05/2018. Data controller:\ Open Data Services Co-operative Limited, 1st Floor, Holyoake House, Hanover Street, Manchester, Greater Manchester, England, M60 0AS. [inbox+opendataservices+443f+data-protection@plan.io](mailto:inbox+opendataservices+443f+data-protection@plan.io).\