diff --git a/docs/components/advocacy_plan.md b/docs/components/advocacy_plan.md index 3b46318..4563689 100644 --- a/docs/components/advocacy_plan.md +++ b/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 diff --git a/docs/components/api_specification.md b/docs/components/api_specification.md index 022e8f4..9bfd774 100644 --- a/docs/components/api_specification.md +++ b/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 diff --git a/docs/components/brand_guidance.md b/docs/components/brand_guidance.md index a5e18dd..43fbaf7 100644 --- a/docs/components/brand_guidance.md +++ b/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 diff --git a/docs/components/case_studies.md b/docs/components/case_studies.md index 87c3bab..daf3788 100644 --- a/docs/components/case_studies.md +++ b/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 diff --git a/docs/components/codelists.md b/docs/components/codelists.md index 4684d4e..9c0f046 100644 --- a/docs/components/codelists.md +++ b/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 diff --git a/docs/components/commitment_templates.md b/docs/components/commitment_templates.md index 5003aff..81bcfdf 100644 --- a/docs/components/commitment_templates.md +++ b/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 diff --git a/docs/components/communication_channels.md b/docs/components/communication_channels.md index 69b84db..48f4d3d 100644 --- a/docs/components/communication_channels.md +++ b/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 diff --git a/docs/components/communications_plan.md b/docs/components/communications_plan.md index 024c8e7..93c07e6 100644 --- a/docs/components/communications_plan.md +++ b/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 diff --git a/docs/components/community_spaces.md b/docs/components/community_spaces.md index 8427e44..c6eb95f 100644 --- a/docs/components/community_spaces.md +++ b/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 diff --git a/docs/components/contributor_guidelines.md b/docs/components/contributor_guidelines.md index 1b63d1e..d0cbfd7 100644 --- a/docs/components/contributor_guidelines.md +++ b/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 diff --git a/docs/components/conversion_tools.md b/docs/components/conversion_tools.md index 2268f91..5543222 100644 --- a/docs/components/conversion_tools.md +++ b/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 diff --git a/docs/components/data_aggregator.md b/docs/components/data_aggregator.md index 61d083e..ce4684e 100644 --- a/docs/components/data_aggregator.md +++ b/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 diff --git a/docs/components/demonstration_applications.md b/docs/components/demonstration_applications.md index e806c0c..e9259c5 100644 --- a/docs/components/demonstration_applications.md +++ b/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 diff --git a/docs/components/developer_guidelines.md b/docs/components/developer_guidelines.md index 2a972c5..a66df7d 100644 --- a/docs/components/developer_guidelines.md +++ b/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 diff --git a/docs/components/development_principles.md b/docs/components/development_principles.md index 5ae9a06..f0fdc42 100644 --- a/docs/components/development_principles.md +++ b/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. diff --git a/docs/components/example_data.md b/docs/components/example_data.md index 27d5a19..0b7eddc 100644 --- a/docs/components/example_data.md +++ b/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 diff --git a/docs/components/faqs.md b/docs/components/faqs.md index a14c466..9c54a8f 100644 --- a/docs/components/faqs.md +++ b/docs/components/faqs.md @@ -1,12 +1,7 @@ # FAQs -## Summary +Frequently Asked Questions (FAQs) are a compilation of common queries and answers designed to guide users and publishers. They are valuable for shaping implementers' understanding early in the process, proactively addressing potential misconceptions before significant effort is expended. Furthermore, FAQs act as a centralised reference resource, documenting established solutions to recurring issues in a single, readily accessible location. -Addressing frequently asked questions from publishers and users. - -## Description - -FAQs cover common issues and questions that are asked, and can be used to shape implementers' thinking very early in their process, addressing misconceptions before too much work happens. They can also be a useful reference resource - common solutions to regular issues can be recorded in a single place. ## Prioritisation Factors diff --git a/docs/components/field_level_mapping_template.md b/docs/components/field_level_mapping_template.md index bb0add3..b708606 100644 --- a/docs/components/field_level_mapping_template.md +++ b/docs/components/field_level_mapping_template.md @@ -1,12 +1,7 @@ # Field-level Mapping Template -## Summary +Field-level mapping provides a mechanism for relating data elements in existing systems to those within a target standard. This mapping, typically performed when preparing to publish data according to a defined standard, helps ensure accurate data transformation and integration. Using a structured template to record these mappings promotes consistency, facilitates collaboration among team members, and allows standards organisations to provide tailored guidance on data transformation, improving the overall quality and usability of the published data. -Used when preparing to publish data to cross-walk from existing systems. - -## Description - -Field-level mapping is a crucial stage in preparing to publish existing data to a standard. A template gives some structure to the activity, can be shared between colleagues, and gives an opportunity for a standard to provide helpful advice in context. ## Prioritisation Factors diff --git a/docs/components/getting_started_documentation.md b/docs/components/getting_started_documentation.md index 2a9e6ec..ec6ed56 100644 --- a/docs/components/getting_started_documentation.md +++ b/docs/components/getting_started_documentation.md @@ -1,12 +1,7 @@ # Getting Started Documentation -## Summary +A learning resources component provides user-friendly guidance and examples to aid in understanding and applying a standard. While normative standard documentation is essential for its technical precision and authoritativeness, learning resources such as worked examples, guided tutorials, and practice materials significantly improve the process of learning and implementing a new standard. These resources cater to different learning styles and provide practical support, making the standard more accessible to a wider audience. -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. ## Prioritisation Factors diff --git a/docs/components/glossary.md b/docs/components/glossary.md index 9677494..5b35797 100644 --- a/docs/components/glossary.md +++ b/docs/components/glossary.md @@ -1,12 +1,7 @@ # Glossary -## Summary +A glossary is a defined list of terms used within a standard, alongside their corresponding definitions. Providing an authoritative and unambiguous list, a glossary ensures clarity and consistency for users of the standard. Definitions offered in a glossary may sometimes differ from pre-existing interpretations among adopters, but these definitions should be understood as the terms are intended to be used within the context of the specific standard. -Providing clear definitions for all the terms of art used in a standard. - -## Description - -A glossary provides an authoritative and unambiguous list of the terms and their definitions as used in a standard. The definitions may be different from some of those used by adopters, but ensure clarity when using the standard. ## Prioritisation Factors diff --git a/docs/components/guidance_documentation.md b/docs/components/guidance_documentation.md index a4bb541..2cf68dd 100644 --- a/docs/components/guidance_documentation.md +++ b/docs/components/guidance_documentation.md @@ -1,12 +1,7 @@ # Guidance Documentation -## Summary +Non-normative guidance provides practical advice on implementing and sharing data using a specific standard. While standards offer detailed, technical definitions for publishing data, derived from considerable research, they often function primarily as reference documentation. To encourage adoption, non-normative guidance acts as a user-friendly walkthrough of the standard's application, drawing on real-world experience to help users understand initial steps, prioritise effort, and grasp core concepts. This type of documentation aids adopters in navigating the complexities of the standard and putting it into practice effectively. -Non-normative guidance on how to share data using the standard. - -## Description - -Standards typically comprise a detailed, technical definition of how to publish data. They are often the product of extensive work and research, and are designed to be reference documentation. However, adoption requires adopters to be guided through the process of adoption - helped to understand how to start, where to focus effort, and how to understand concepts. Guidance documentation takes adopters through the process of using the standard, building on real-world experience. ## Prioritisation Factors diff --git a/docs/components/helpdesk_service.md b/docs/components/helpdesk_service.md index fff650b..70757ba 100644 --- a/docs/components/helpdesk_service.md +++ b/docs/components/helpdesk_service.md @@ -1,26 +1,7 @@ # Helpdesk Service -## Summary +A helpdesk facilitates engagement with a data standard, providing implementers and users with support and guidance. This support may be provided through a helpdesk email address, offering an accessible and asynchronous channel for answering questions related to the standard; this can be managed by an individual or a team sharing an inbox. A direct phone number can also offer rapid access to implementation support, fostering relationships between implementers and standard maintainers and encouraging frequent engagement, though some issues are better addressed through other channels. A Customer Relationship Management (CRM) system can be a valuable tool for managing interactions with a standard, enabling outreach and engagement with potential adopters, users and champions, as well as tracking communication. CRMs further aid in knowledge management by recording interactions with specific adopters, ensuring cohesive technical support and policy engagement, and providing consistent answers to technical queries. They also enable time tracking, whether for charging purposes or for identifying adopters requiring the most support. Reporting features within a CRM can be used to monitor progress towards adoption metrics and to evaluate helpdesk performance. Useful features for supporting a standard include contact profiles, task tracking, agile boards, email integration or a dedicated email helpdesk, and a knowledge base. -Providing a place to ask implementation questions and direct access to talk to someone about adopting the standard. A Contact Relationship Management (CRM) system can be used to track the different actors engaging with a standard, including implementers, users and support providers. - -## Description - -* A *helpdesk email address* provides an accessible, on-demand, asynchronous way for questions about the standard to be answered. They may go to a single person, or a team may share an inbox and prioritise work accordingly. -* A *direct phone number* provides rapid access to implementation support, and can help to build relationships between implementers and those maintaining the standard. It can encourage little-and-often access to support, which may help implementers avoid early misunderstandings. However, many implementation issues require sharing of data or in-depth investigation, which can't be easily carried out over the phone. -* A *CRM* may be used for: - - **Outreach and engagement** - identifying potential standard adopters, users and champions, and keeping track of communication and engagement with them; - - **Knowledge management** - keeping track of communication with particular standard adopters; making sure technical support and policy engagement is joined up; and providing access to consistent technical support answers; - - **Time tracking** - to supported charging by helpdesk consultants, or to allow reporting on which adopters require the greatest investment of time and support; - - **Reporting** - to track progress towards key adoption metrics, and to measure key performance indicators for a helpdesk; - -Useful CRM features for supporting a standard include: - -- Contact profiles -- Task tracking -- Agile board -- E-mail integration or e-mail helpdesk -- Knowledge base ## Examples diff --git a/docs/components/icons.md b/docs/components/icons.md index 1b360c4..ba2fb48 100644 --- a/docs/components/icons.md +++ b/docs/components/icons.md @@ -1,12 +1,7 @@ # Icons -## Summary +Icons are visual cues employed in documentation and presentations to aid understanding and recall. The consistent use of icons across various assets enhances recognition and can contribute to building trust and reinforcing key concepts for the audience. -Common visual elements used across documentation and presentations. - -## Description - -Icons help with recall of key concepts, and consistency across a range of assets helps to build trust. ## Prioritisation Factors diff --git a/docs/components/implementation_plan_template.md b/docs/components/implementation_plan_template.md index 096887d..71aa2c7 100644 --- a/docs/components/implementation_plan_template.md +++ b/docs/components/implementation_plan_template.md @@ -1,12 +1,7 @@ # Implementation Plan Template -## Summary +The Implementation Plan Template provides a structured overview for planning the implementation of a standard. This template outlines the necessary stages, key considerations, and preparatory steps required for successful implementation. Utilising an implementation plan enhances confidence among implementers and stakeholders, ensuring a smoother process. Furthermore, a well-defined plan enables the standard provider to offer proactive support, rather than simply reacting to ad-hoc queries, improving the overall adoption experience. -To be filled in by someone planning to adopt the standard. - -## Description - -The Implementation Plan Template provides an overview of the planning required for an implementation - the stages to go through, the factors to consider, the preparation required, and the path to implementation. Having a plan provides confidence of success for implementers and stakeholders, and helps the standard to provide support proactively instead of just responding to questions. ## Prioritisation Factors diff --git a/docs/components/issue_tracker.md b/docs/components/issue_tracker.md index 0c743c3..96399f7 100644 --- a/docs/components/issue_tracker.md +++ b/docs/components/issue_tracker.md @@ -1,12 +1,7 @@ # Issue Tracker -## Summary +An issue tracker is a centralised system for recording and managing discussions regarding proposed changes to data standards. These discussions, along with suggestions for improvements, can originate from various sources, including technical and policy forums, in-person conversations, and private communications; the issue tracker consolidates them into a single, accessible location. By maintaining a clear audit trail of these discussions, an issue tracker allows the community to understand the rationale behind decisions and facilitates future discussions if modifications are desired at a later date. This ensures transparency and continuity in the evolution of the data standard. -Providing clear public trail for all discussions about changes to the standard. - -## Description - -Discussions around changes to data standards and suggestions for improvements often happen in different places - in technical and policy forums, in person, in private chats and elsewhere. An issue tracker provides a single place where such discussions are recorded, and discussion can advance. Later, an issue tracker allows the community to see the rationale behind a decision, allowing discussion to pick up if a change is desired. ## Prioritisation Factors diff --git a/docs/components/logo.md b/docs/components/logo.md index b66e90f..fdf98aa 100644 --- a/docs/components/logo.md +++ b/docs/components/logo.md @@ -1,12 +1,7 @@ # Logo -## Summary +A logo for a standard is a visual element used to represent and identify that specific standard. The logo serves to strengthen the standard's brand identity, providing a readily recognisable visual cue within documentation and resources. Furthermore, with appropriate authorisation, adopters of the standard can utilise the logo to illustrate their adherence and implementation of the standard. -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 ## Prioritisation Factors diff --git a/docs/components/maintenance_handbook.md b/docs/components/maintenance_handbook.md index e207154..49d6329 100644 --- a/docs/components/maintenance_handbook.md +++ b/docs/components/maintenance_handbook.md @@ -1,12 +1,7 @@ # Maintenance Handbook -## Summary +A maintenance handbook is a resource designed for the team responsible for developing and upholding a particular standard. It serves as a central repository for decisions, established best practices, and resolutions to frequently encountered issues. This handbook is also a crucial tool for onboarding new team members and facilitating knowledge transfer when personnel changes occur. By clearly outlining standard operating procedures, the maintenance handbook can encourage wider participation in the standard's maintenance, ensuring that even infrequent contributors are well-informed and can contribute effectively. -For the team maintaining and updating the standard. - -## Description - -The maintenance handbook provides a place for the team developing and maintaining the standard itself, to record decisions and best practices, to store solutions to common problems, and to hand over as people leave and join the team. It can be used to encourage wider contribution to the maintenance, by ensuring that even occasional contributors understand the practices of the standard. ## Prioritisation Factors diff --git a/docs/components/publication_statistics_dashboard.md b/docs/components/publication_statistics_dashboard.md index f6fdc76..83bcdd3 100644 --- a/docs/components/publication_statistics_dashboard.md +++ b/docs/components/publication_statistics_dashboard.md @@ -1,20 +1,7 @@ # Publication statistics dashboard -## Summary +A dashboard provides a centralised location to access reports and visualisations relating to the adoption and quality of data adhering to a particular standard. This tool addresses key questions about publisher engagement, such as who is publishing data using the standard, and how many publishers are using specific versions (e.g., version 1.0 or 1.1). It also enables analysis of data usage, including how many publishers are utilising particular fields and what values they are employing within those fields. Furthermore, the dashboard supports the monitoring of codelist usage and identification of common validation errors. Critically, it can help to assess the impact of potential changes to the standard, for instance, by identifying which publishers would be affected by the deprecation of a specific field. -A single location for accessing reports on the number of publishers, status of current publication, validation errors, coverage of key fields, use of extensions and other key facts. - -## Description - -A dashboard helps to answer questions like: - -- Who is publishing using the standard? -- How many publishers are using version 1.0 or 1.1? -- How many publishers are using this specific field? -- What values are used in this specific field? -- Which codelists are publishers using? -- Which are the most common validation errors? -- If we deprecate a particular field, which publishers will be affected? ## Examples diff --git a/docs/components/recommended_data_license.md b/docs/components/recommended_data_license.md index fa47a00..b656425 100644 --- a/docs/components/recommended_data_license.md +++ b/docs/components/recommended_data_license.md @@ -1,12 +1,7 @@ # Recommended Data License -## Summary +A recommended licence is a suggestion for the type of licence that publishers should use, such as Creative Commons or the Open Database Licence. Recommending a licence encourages adopters to carefully consider licensing implications and establish a robust standard. This helps to set a high bar for adopters and foster inertia within the standard's user community, promoting consistency and best practice. -E.g. the requirement that publishers should use Creative Commons or Open Database License. - -## 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. ## Prioritisation Factors diff --git a/docs/components/tutorial_videos.md b/docs/components/tutorial_videos.md index 90f5e41..b3edbfd 100644 --- a/docs/components/tutorial_videos.md +++ b/docs/components/tutorial_videos.md @@ -1,12 +1,7 @@ # Tutorial Videos -## Summary +On-demand video tutorials offer immediate guidance on using the standard. These videos provide a convenient pathway through available learning materials, allowing users to grasp concepts and workflows at their own pace. -Providing on-demand overview of how the use the standard. - -## Description - -Videos provide the opportunity to deliver a path through learning materials that are available on-demand. ## Prioritisation Factors diff --git a/docs/components/validator.md b/docs/components/validator.md index d80bc0c..956c2a3 100644 --- a/docs/components/validator.md +++ b/docs/components/validator.md @@ -1,11 +1,5 @@ # Validator and Quality Tool -## Summary - -Providing a report on technical validity of data against the schema. Providing feedback on the content of datasets, based on a set of data quality rules. Machine and human-readable rules used to check data quality. - -## Description - -Part of a standard is often schema, and reporting on technical validity against the schema is a way of programmatically checking that the data conforms to the schema and can be used by other tools that expect data to conform to the schema. By providing validation as an online service, implementers can validate their data without +A data quality report provides feedback on the technical validity and content of datasets. This report uses a set of machine-readable and human-readable data quality rules to assess data, and it flags any discrepancies. Often, this includes validating data against a schema to ensure it conforms and can be readily processed by other tools. Implementing validation as an online service allows users to readily assess their data without needing to set up their own complex validation environments. diff --git a/docs/components/website.md b/docs/components/website.md index b9e37d2..1eda13b 100644 --- a/docs/components/website.md +++ b/docs/components/website.md @@ -1,12 +1,7 @@ # Website -## Summary +A standard's website acts as a central shop-window, showcasing the various components and contextualising them within broader goals. This provides a single, accessible location where the standard can be clearly explained and targeted towards different user groups. Crucially, it also serves as a discovery point for adopters seeking resources and guidance. -A shop-window on the standard, setting in context of wider goals - -## Description - -A standard's website brings together the various component of a standard, giving a single place where the standard can be explained to different audiences, and will act as a place that adopters go to in order to discover resources. ## Prioritisation Factors