Components: Combine summaries and descriptions

docs/components/advocacy_plan.md

@@ -1,12 +1,7 @@
 # Advocacy Plan
 
-## Summary
+An advocacy plan details the steps and resources required to promote the adoption of a standard by organisations, alongside outlining key supporting arguments. This plan should be proactively maintained and updated to reflect the standard's maturity and its evolving impact on the relevant field. It serves as a roadmap for encouraging uptake and showcasing the benefits of adherence.
 
-Setting out steps to encourage organizations to adopt the standard.
-
-## Description
-
-An advocacy plan provides the resources and sets out the steps that will be followed to encourage organisations to adopt a standard, as well as key arguments. It should be updated regularly as the standard matures and as the standard starts to have an impact.
 
 ## Prioritisation Factors
 

docs/components/api_specification.md

@@ -1,12 +1,7 @@
 # API Specification
 
-## Summary
+An application programming interface (API) specification details how data should be accessed interactively. APIs allow developers to tap into datasets stored elsewhere, without the burden of downloading and processing entire files. This lowers the entry barrier for building data-driven applications, promoting wider use of the information. Moreover, an API specification establishes a standardised format for API developers to present data interfaces; this fosters portability for consuming applications across different publishers and eliminates the initial design costs for new data publishers wishing to use an API.
 
-Describing how data should be accessed interactively.
-
-## Description
-
-APIs allow developers to access data stored elsewhere without needing to obtain and process the whole data set themselves. This lowers the barriers to creating applications that use the data, and encourages use. An API specification sets out a standard way for API developers to present interfaces to the data, meaning that consuming applications are more portable between publishers and removing the design cost for any adopter wishing to publish via an API
 
 ## Prioritisation Factors
 

docs/components/brand_guidance.md

@@ -1,14 +1,7 @@
 # Brand Guidance
 
-## Summary
+Brand guidance defines how the name, logo, visual style and other identifying marks of a standard should be used. This guidance is crucial for preventing misrepresentation of the standard and ensuring a clear distinction between the standard itself and those implementing it. For standards that have established a brand, clear guidance is necessary to ensure its beneficial use by the community and within the standards context. This includes specifying when the logo is permissible for use, advising how tools and implementations should describe their relationship to the standard, and making sure the brand is only employed in relevant situations.
 
-Describing how to use the logo and how to talk about the standard and setting out who is allowed to use the logo, and how implementers should describe their relationship to the standard.
-
-## Description
-
-Brand guidance sets out how to use the name, logo, look-and-feel and other identifying marks and conventions. The guidance helps a standard ensure that it isn't misrepresented, and that there is a clear distinction between the standard and those using it.
-
-Standards that have developed a brand need to ensure that it is used in a way that benefits the community and the standard. This will likely include guidance as to when the logo can be used, how tools should describe themselves relative to the standard, and ensure that the brand is only used when relevant
 
 ## Prioritisation Factors
 

docs/components/case_studies.md

@@ -1,12 +1,7 @@
 # Case Studies
 
-## Summary
+Case studies offer concrete, real-world examples illustrating the impact of adopting a given standard. These write-ups, often presented as narrative stories accessible to a general audience, demonstrate how a standard has been applied in practice and the benefits it has delivered. Crucially, case studies also provide a platform for frank discussion of the challenges encountered during implementation. This helps manage expectations among potential adopters and reassures those currently in the process that facing difficulties is a normal part of the adoption process.
 
-Accessible write-ups exploring adoption and impact through narrative stories for a general audience.
-
-## Description
-
-Case studies give real-world examples of when use of a standard has enabled a particular impact, while giving space for frank discussion of the challenges faced. This helps to set expectations among potential adopters and encourages those currently going through adoption of a standard to be reassured that encountering challenges isn't exceptional.
 
 ## Prioritisation Factors
 

docs/components/codelists.md

@@ -1,12 +1,7 @@
 # Codelists
 
-## Summary
+Codelists are lists of terms that are provided as part of a standard to restrict field values to a defined set of options, ensuring data consistency and accurate mapping of concepts across datasets. For instance, a codelist specifying currency codes prevents inconsistencies such as representing US Dollars as both "$" and "USD". Codelists can be either open, allowing for the addition of new values, or closed, where the defined set of values is fixed and additions are not permitted.
 
-Classifications used in the standard
-
-## Description
-
-Codelists are lists of terms that are provided as part of a standard in order to ensure that values of fields where there are a limited range of options are properly limited in the data, and that concepts map correctly between datasets. For example, a codelist might specify currency codes, to avoid US Dollars being referred to as "\$" in one data set and "USD" in another. Codelists can be open or closed - open codelists allow values to be added, while closed codelists do not permit additions
 
 ## Prioritisation Factors
 

docs/components/commitment_templates.md

@@ -1,12 +1,7 @@
 # Commitment templates
 
-## Summary
+A draft commitment is a template for potential adopters to adapt, sign, and then publish to demonstrate their support for a given standard. By offering this draft, the standard ensures prospective adopters are fully aware of the expected commitment levels from the outset. Furthermore, providing an easily adaptable template reduces the likelihood of implementers creating their own, weaker adoption commitments, ensuring a higher and more consistent standard of adoption across the board. This approach essentially removes barriers to a robust adoption process.
 
-Asking potential adopters to sign-up and give their support to the standard.
-
-## Description
-
-Draft commitments are templates for adopters to copy or adapt before signing and making public. By providing a draft, a standard can ensure that adopters are aware of what they are expected to commit to at the start of the process, and by providing a path of least resistance to a high bar of adoption, a standard organisation can ensure that there is less risk of implementers crafting their own, lower, commitment to adoption.
 
 ## Prioritisation Factors
 

docs/components/communication_channels.md

@@ -1,17 +1,7 @@
 # Communication channels
 
-## Summary
+Communication channels are mechanisms employed to engage with implementers, users, and other stakeholders regarding a data standard. Different channels are suited to various audiences and content formats; for example, a regularly updated blog can provide community updates, valuable resources, and showcase the standard's maintenance and usage. Public social media channels, like LinkedIn pages, allow for frequent communication and community engagement in an accessible manner. If an open community already uses microblogging sites, employing those sites reduces barriers to participation. Email lists offer a low-cost and widely accessible means for group discussions, often with public archives to ensure accountability. Standards frequently operate both a discussion list and a separate announcement list, letting members choose their level of engagement. The asynchronous nature of email lists lets users participate as frequently or infrequently as they wish; however, some may avoid public email lists, fearing that their questions or learning processes will be permanently recorded.
 
-Used to communicate with implementers, users and other stakeholders.
-
-## Description
-
-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.
-
-* 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
 

docs/components/communications_plan.md

@@ -1,12 +1,7 @@
 # Communications Plan
 
-## Summary
+A communications plan outlines the intended steps to promote media coverage of a standard. This plan ensures proactive pursuit of media opportunities and prepares representatives of the standard to effectively engage with the media. By providing a structured approach, a communications plan helps ensure that the standard is accurately portrayed, and that realistic expectations are set among potential users and beneficiaries.
 
-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.
 
 ## Prioritisation Factors
 

docs/components/community_spaces.md

@@ -1,15 +1,7 @@
 # Community spaces
 
-## Summary
+Online community spaces facilitate discussions about a standard, its adoption, and its use of data. These spaces typically include both discussion forums and chat channels. A discussion forum allows for a complete audit trail of decisions, which can be retained and referred to later. Over time, these forums become a valuable resource for implementers and provide rich content for support articles, FAQs and other supporting resources. In addition to forums, a chat channel, such as Slack, provides a medium for less structured, real-time conversations with the community about the development, adoption and ongoing use of the standard.
 
-Online spaces for community discussion of the standard, adoption and data use.
-
-## Description
-
-Online spaces for community discussion of the standard, adoption and data use:
-
-* A *discussion forum* provides complete audit trail for decisions can be retained and referred to. Over time, forums can become a valuable resource for implementers, and provide rich content for support articles, FAQs and other resources.
-* A *chat channel* (e.g. Slack) allows for conversations with the community about development, adoption and use of the standard.
 
 ## Prioritisation Factors
 

docs/components/contributor_guidelines.md

@@ -1,12 +1,7 @@
 # Contributor Guidelines
 
-## Summary
+Contributor guidelines outline the procedures and workflows for contributing to a policy-related data standard or its associated documentation. These guidelines establish expectations for external contributions, including aspects such as licensing requirements and the process by which contributions are reviewed and acknowledged. Contributor guidelines can encompass a range of input, from informal comments in forums or emails to more formal, written contributions. The goal is to ensure consistency and quality, and also to streamline the adoption and improvement of the standard.
 
-Describing the practices and workflows for contributing to the standard or associated documentation.
-
-## Description
-
-Contributor 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, acknowledgement, and expectations around process. Contributions may include comments in forum threads or in emails as well as formal written contributions.
 
 ## Prioritisation Factors
 

docs/components/conversion_tools.md

@@ -1,12 +1,7 @@
 # Conversion Tools
 
-## Summary
+This component describes the ability to convert data between different serialization formats. Data standards frequently utilise structured formats like JSON or XML to provide greater modelling flexibility and enable schema validation, which developers generally find easier to manage programmatically. However, JSON and XML are not particularly user-friendly; therefore, many users prefer flat representations like CSV files or XLSX spreadsheets for data publication and manipulation. Conversion tools bridge this gap, allowing standards and developers to leverage the advantages of structured data formats, while simultaneously enabling users to interact with the data in a familiar and accessible manner.
 
-Allowing conversion between serialization 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.
 
 ## Examples
 

docs/components/data_aggregator.md

@@ -1,12 +1,7 @@
 # Data Aggregator
 
-## Summary
+A data aggregator provides access to all the data shared using a specific standard. Many standards recognise that a key benefit of standardisation lies in the potential for applications that utilise the entire dataset. A data aggregator consolidates some or all of the data published according to the standard, enabling users to acquire it as a unified dataset. This removes the initial hurdle of individually sourcing and compiling the data, thereby fostering application development and encouraging experimentation.
 
-Providing access to all the data shared using the standard.
-
-## Description
-
-Many standards consider one of the best arguments for standardisation is being able to give examples of applications that become possible when the entire data set can be taken as a whole. A data aggregator brings together some or all of the data being published to the standard and enables users to obtain it as a single data set, removing the first barrier to application development on top of the data set, and encouraging experimentation.
 
 ## Prioritisation Factors
 

docs/components/demonstration_applications.md

@@ -1,12 +1,7 @@
 # Demonstration Applications
 
-## Summary
+Demonstration applications are examples, either real-world or simulated, which use standardised data to showcase the potential applications and benefits of the standard. These applications can serve as powerful illustrations, highlighting the advantages of adopting the standard as a whole, or specific elements within it. They effectively demonstrate the real-world utility and impact that can be achieved when data is structured and published according to a defined standard.
 
-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.
 
 ## Prioritisation Factors
 

docs/components/developer_guidelines.md

@@ -1,12 +1,7 @@
 # Developer Guidelines
 
-## Summary
+Developer guidelines outline the coding practices and workflows expected for contributions to a standard or its associated tools. These guidelines aim to ensure consistency and quality when incorporating external contributions and typically cover several key aspects. These include licensing requirements, the procedure for submitting and reviewing contributions, expectations regarding the overall contribution process, and specific technical expectations. The technical expectations often encompass elements such as commenting practices, naming conventions, the inclusion of tests, and adherence to a specific coding style. By establishing these clear expectations, developer guidelines facilitate effective collaboration and maintain the integrity of the standard and supporting tools.
 
-Describing the coding practices and workflows for contributing to the standard or associated tools.
-
-## 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.
 
 ## Prioritisation Factors
 

docs/components/development_principles.md

@@ -1,11 +1,5 @@
 # Development Principles
 
-## Summary
-
-Setting out high-level goals that adoption of the standard works towards.
-
-## Description
-
-Principles help to focus work around a standard, provide encouragement for those working for the standard as to the purpose of their effort, and provide a 'litmus test' for proposals
+Principles are high-level goals that adoption of a standard aims to achieve. These guiding statements help to focus work related to the standard, providing encouragement and clarity of purpose for those involved. Furthermore, principles act as a ‘litmus test’ against which proposals and potential changes can be evaluated, ensuring alignment with the overall objectives of the standard.
 
 

docs/components/example_data.md

@@ -1,12 +1,7 @@
 # Example Data
 
-## Summary
+Example data offers illustrative instances of data conforming to a specific standard. These examples, whether automatically generated or manually created, are invaluable for both tutorial purposes and for rigorously testing the standard's implementation. Adopters and users frequently benefit from observing tangible data examples, which can provide insights and clarify expectations that might be overlooked within formal documentation. Example data can serve as a crucial guide, especially when defining the expected format and content of the data within a given standard.
 
-Auto-generated and manually created examples used in tutorials, and for testing the standard.
-
-## Description
-
-Adopters of the standard and users of the data are often helped by seeing examples of what the data could look like. Example data can often give hints that might be missed by reading documentation, and can be used to set expectations of what data should look like.
 
 ## Prioritisation Factors