-
Notifications
You must be signed in to change notification settings - Fork 46
Google Season of Docs 2021 Project Ideas
WRITER SELECTED: Thank you to all the technical writers who expressed interest in this project. We are excited to work with @ColinMaudry, who has excellent experience with ontologies, procurement and OCDS itself.
TECHNICAL WRITERS: If interested in this project, please contact James McKinney, [email protected]. Please also refer to the Google Season of Docs Technical writer guide to prepare your statement of interest.
Please submit your statement of interest by May 3.
Our world runs on public contracts. We make sure they are open, fair & efficient. The Open Contracting Data Standard (OCDS) is a core product of the Open Contracting Partnership (OCP), which enables disclosure of data and documents at all stages of contracting processes by defining a common data model. It was created to support organizations around the world to increase contracting transparency, and allow deeper analysis of contracting data by a wide range of users. Version 1.0.0 was developed for the Open Contracting Partnership by the World Wide Web Foundation and the World Bank in 2015. We’re now on version 1.1.5 which was released in 2020.
Our contributors come from all over the world. Most of our contributors are individuals and organizations with a background in public transparency who have a range of technical capabilities (from very basic to very advanced). Our biggest users are governments that are implementing OCDS in efforts to make billions of dollars in procurement data more open to the public. We also work with a variety of users of OCDS data including civil society organizations, journalists, and governments themselves to analyze OCDS data and improve policies around public procurement.
OCDS has undergone a variety of changes since its initial release and now targets a variety of types of users. In the past year, OCDS' reference documentation has been updated with new definitions and terms designed to add clarity to the documentation. However, our supplementary guidance and explainers have not been updated to align with our new reference material. This can lead our newest and least technical users into challenges as they may encounter new materials and terms when they arrive at our reference documentation.
Improving our guidance materials to align them with new reference documentation will create consistency and clarity across all of our documentation. It will also help expand our community of users and allow more people from a variety of backgrounds to get started publishing and using open contracting data!
Our work to align OCDS guidance materials to our updated schema will focus on:
- Auditing guidance materials to identify places where new reference schema is not accurately represented
- Working with the OCDS community and helpdesk team to update guidance materials in line with reference changes
- Outlining a process to be followed in future versions of OCDS to ensure that updates to reference will be captured in guidance materials
- Creating a common template for a “how-to” guide which will apply to all our guidance materials
- Developing worked examples from current case studies to show new users how other organizations have gone through the process of implementing OCDS
Work that is out-of-scope for this project:
- This project will not create new types of guidance materials, instead focusing on reorganizing and updating our existing materials.
A technical writer for this project would need:
- Understanding of technical definitions detailed in our reference schema
- Ability to reconcile differences across OCDS versions with a focus on clarity
- Ability to translate technical documentation into easy-to-understand language
We estimate that this work will take three months to complete. We are actively seeking additional technical writers to help us flesh out the details and provide additional perspectives on our documentation. The Open Contracting Partnership (the OCDS governing steward) and OCDS community members have committed to supporting the project, which includes the standard's editor and other technical writers.
We will gather qualitative feedback on guidance materials by testing with existing users across a variety of types. Qualitative feedback and user testing will focus on:
- Accuracy - do the guidance materials accurately represent reference documentation?
- Logical flow - do the guidance materials present information in a logical way?
- Ease of use - is it easy to find what you need across guidance materials and reference documentation?
OCDS is used in a variety of ways and we track that usage in order to continuously improve our documentation. For this project, our main objective is to improve guidance materials and thus the main metric for tracking success is the number of people accessing and using these materials. We will track three metrics to gauge usage of guidance materials:
- Number of page visitors to guidance materials (web analytics → increase)
- Number of new page visitors to guidance materials (web analytics → increase)
- Number of questions to our helpdesk requesting support/clarity on technical definitions (helpdesk tickets → decrease)
| Item | Amount | Notes |
|---|---|---|
| Technical writer | 12,000 | |
| Design work | 2,500 | A main contributor to the Executable Books project will improve navigation to make guidance easier to find, and add interface elements to give pages a visual hierarchy. |
| User testing | 500 | The project team will test the new documentation with users to collect feedback and identify fixes or future work. |
| Total | 15,000 |
Previous experience with technical writers or documentation: The project's team includes many technical writers who have contributed to the OCDS documentation, both in terms of content and technology (writing Sphinx extensions, etc.).
In terms of resources, we will give the technical writer an orientation to the project, and add them to a Slack channel for project communication. We have an extensive handbook for contributing to the documentation (see the shorter Contributing page). The project uses Sphinx with Markdown. The technical writer will be supported by the standard's editor, subject matter experts, and other technical writers.
In terms of workflow, contributors create and discuss issues on GitHub. This is the opportunity to clarify the problem and agree on solutions. If the issue is thorny, contributors can discuss the issue on a call. If the issue involves authoring a lot of new content, a technical writer drafts an outline for review before filling in the content. Then, the technical writer authors a pull request, which is reviewed by one or more contributors. If the review requires discussion, a call is organized. A draft website is automatically built, which is especially useful when reviewing changes to the user interface. After discussing and resolving all comments, the pull request is approved and merged.