Skip to main content

Help us write OpenRefine's new documentation

· 4 min read

The OpenRefine team is seeking a technical writer to help write a reference manual for the tool. This is a 6 months contract, funded by a grant from the Silicon Valley Community Foundation via the Chan Zuckerberg Initiative under their Essential Open Source Software for Science programme.

OpenRefine is a fiscally sponsored project of Code for Science & Society Inc, a 501(c)(3) charitable organization in the US.

Experience

We are looking for one or more enthusiastic contributors to join our fully remote team, to help us write a reference manual for OpenRefine. The following skills are key:

  • Ability to write documentation fluently in English. Experience with writing software documentation is ideal but not necessary;
  • Experience with OpenRefine as a user and ideally as a trainer (writing tutorials, running workshops or developing any other training material);
  • Familiarity with GitHub, as documentation changes will be reviewed there, and much of our project planning is also happening there. Our documentation is written in Markdown, for which there exists many visual editors (for instance, plugins to export from Google Docs to Markdown, or the HackMD online editor).

Overview of the work

As part of our milestones for the EOSS grant, we are in the process of migrating our existing documentation from our GitHub Wiki to a dedicated documentation platform. This effort is described in our root planning document and coordinated by Owen Stephens and Antonin Delpeuch. We have identified multiple documentation areas:

  • Product reference, documenting for users all the features offered by the tool in a systematic fashion;
  • Technical reference, aimed at developers, explaining the architecture of the tool;
  • Project documentation, aimed at anyone who wants to contribute code, translations, documentation, user support around OpenRefine;
  • Tutorials and how-to guides, showing by example how the tool can be used for specific data cleaning problems;
  • Discussions, to support users with their specific issues.

You will be working on the product reference only. The goal for this documentation is to provide a thorough and systematic description of the behaviour of all user-facing features of the tool, such as:

  • Operations
  • Importers
  • Exporters
  • GREL functions
  • Facets
  • Bundled extensions such as Jython and the Wikidata integration

This reference documentation is meant to support users in their exploration of the tool. Users will typically discover the tool through existing tutorials or workshops: these introductory training materials can refer to the product documentation to help users dive deeper in the concepts demonstrated by the course.

The product reference will be written in Markdown using Docusaurus. Documentation for a sample operation is provided as an example of what we are aiming for:

Your task will be to write similar documentation for other functions of the tool.

Compensation and timeline

We have 25,000 USD available to complete these milestones. The payment details will be negotiated with the contractor(s).

The work could be done by a single individual or by a team, depending on the availability of applicants.

We are aiming to hire one or more technical writers for this task by the end of May 2020.

How to respond

Update (2020-05-18): the application period for this position has lapsed, thank you to everyone who got in touch. We will announce the results in the coming weeks.

Please send your resume or CV, sample of your relevant previous work and a short letter of interest to advisory.committee@openrefine.org. We will schedule an interview with short-listed candidates.

Code for Science & Society is an equal opportunity employer committed to hiring a diverse workforce at all levels of the organization, creating a culture that allows us to better serve our projects, our employees, and our communities. We value and encourage the contributions of our employees and strive to create an environment where everyone can reach their full potential and drive outstanding results. All qualified applicants will receive consideration for employment without regard to race, national origin, age, sex, religion, disability, sexual orientation, marital status, veteran status, gender identity or expression, or any other basis protected by local, state, or federal law. This policy applies with regard to all aspects of one’s employment, including hiring, transfer, promotion, compensation, eligibility for benefits, and termination.