Back to latest

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 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.

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:

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.

Related Stories