Open Contracting Data Standard: how can we improve the documentation?

The improvements prioritized in this blog have been reflected in version 1.1.5 of the OCDS.

Over the last few months, we’ve been exploring how to improve technical documentation for the Open Contracting Data Standard. The documentation, found at standard.open-contracting.org and available in French and Spanish, is a key resource for both data publishers and data users. It provides explanations and reference material on how to structure and interpret standardized data on public contracting.

We get great feedback on the documentation, and it receives hundreds of visits every week. However, as more and more institutions are adopting the OCDS, publishers are seeking to provide increasingly complete representations of their contracting processes. We’ve been concerned that sometimes the documentation might fall short of meeting users’ needs.

So we set out to better understand how the documentation is now being used, and what we can do to improve it. Our data collection comprised a web survey and interviews with key stakeholders, including data publishers and analysts, members of the OCDS helpdesk and team members from the Open Contracting Partnership, along with the use of web analytics and a review of the approach taken to documentation in other standards.

We’ve summarised some of the key findings below.

Understanding our users

The OCDS documentation has a range of audiences, including technical implementers planning or carrying out work to generate OCDS data, advocates pushing for adoption of the OCDS or for greater contracting transparency, policy makers deciding whether to adopt the OCDS or managing a process of adoption, and analysts working with published OCDS data.

Figure 1. Who uses the OCDS documentation?

However, the current focus of the documentation is primarily on technical implementation and so it is often perceived by other audiences as overly complex and technical, or not directed at them. This can be a barrier to newcomers to the standard

The current emphasis on preparing and publishing data can also leave a gap for those who want to understand how to use published data. A key improvement could be to provide more guidance on “What can be done with OCDS data?” with signposting to relevant open source tools that can support data use.

We also found a perception that the documentation is currently slanted towards central government implementations and could take local government implementations of OCDS into account more, recognizin that cities and municipalities are increasingly adopters of OCDS.

Completing the task

We identified the need to better help users complete a number of tasks through the standard documentation and associated resources.

• Selecting a data standard. Users need to know if the OCDS is the right standard for their needs. This requires clear information on what the OCDS is, and what it is not, as well as information to help situate where it fits in with other standards.
  

• Publishing to OCDS. We found that many of our users are neither policy makers nor technical implementers, but are involved in project management and coordination. They are looking for more information on the process of implementation. Whilst we currently provide detailed field-level reference information, those involved in planning publication of OCDS data are also looking to understand the overall structure and data model, which could be aided by a higher-level view onto the fields and relationships, and more information on possible technical architectures for OCDS publication.
  

• Modeling specific data. For technical publishers, their questions about how to model particular fields could be better answered if the documentation linked to other sources. These might include existing GitHub discussions or examples where that field has been described or explained in more detail before. In particular, publishers are looking for detailed examples from other publishers’ experience of using certain fields.
  

• Locating and creating extensions. Extensions were fully introduced in OCDS 1.1 and are one of the major sources of inquiries to the OCDS helpdesk. Improved documentation could help solve many user questions regarding extensions by, for example, improving extension presentation and showing who created each extension. We already have a blog post explaining ways to handle extra fields that might also help users navigate extensions, but this is currently difficult to find from within the documentation.
  

• Finding and using data. For data analysts, there is a clear need for the documentation to better help users understand how to find and use OCDS data.
  

• Setting targets and assessing quality. At the policy level, publishing countries are often keen to set targets for, or assess, the quality of their data. In particular, national governments are most interested in who else in their region is publishing OCDS data and how good their data is. Whilst the OCDS validator gives some feedback on the structural quality of data, the helpdesk undertakes a lot of work to provide more detailed feedback.

What’s next

Alongside our review of how users engage with the OCDS documentation, we’ve been doing work to sharpen up our use of language in the documentation. Over the coming months, we’ll be starting to work up improvements, including proposals to:

• Draw a clearer separation between the technical specification and implementation resources such as a primer and guidance.
  
• Rework our examples to draw upon more real-world examples of OCDS data.
  
• Build an updated extensions directory and update the way extensions are presented.
  
• Improve search tools within the standard documentation.

We’ll be seeking community input along the process, so please do look out for opportunities to give your feedback. You can become a member of the Open Contracting online community by subscribing to the mailing list.

If you would like to see more of the background to our documentation review, you can access our full review report.