Requesting Feedback: Documenting OpenRefine Community Handbooks

I am following up on my earlier post regarding creating contributor pathways and an organization handbook. I have been enrolled in the CSCCE Community Playbook workshop for two weeks now, and I wanted to share my progress and request early feedback.

So far, I have identified the following handbook:

1. About OpenRefine: to improve transparency on how the project operates.

2. Contributor Pathways: to provide transparency on how one can gain or lose access, set norms and expectations regarding each role, and help new contributors onboard and grow as leaders.

3. OpenRefine Operation Manual: with more detailed procedures on how the project is managed.

I have created a scaffold of the three handbooks in this Google Document. The document is open for comments and suggestions as it is a work in progress. For each section, I am linking existing documents and indicating the status of each section. Please feel free to add what I missed and challenge the draft content.

I am using the Google Document format to create the first edition and brainstorm. My goal is to publish the information on OpenRefine/ Some of the content will be included in the documentation, while other parts will be included on the main website. By doing this, we can track changes using pull requests on GitHub. Additionally, hosting the content on the website will make it easily accessible for non-contributors. We can also take advantage of the Docusaurus and Algolia search interface.

Through February, I will continue to revise the Google Document. I am looking forward to your feedback and inputs either in the forum or in the document.


I wanted to give you an update on my progress with revising the handbook. The last week I focuses on two aspects

  1. Who and when will we update each section. I have added note in each section header regarding potential update schedule and document ownership.

2). I focused on how to present the About OpenRefine section. I believe it should be made directly available on the website as the target audience includes General Public, Contributors, and Partners.

Therefore I revisited the page organization on the website as presented in the screenshot below (link to the source document)

The footer is reorganized into four sections:

  • Get OpenRefine focuses on resources to
    • Download page remains the same
    • What's new redirect to the release note
    • Extensions page remains the same
    • Other distributions page remains the same
    • I want to add a new page to present the OpenRefine ecosystem and how extension, reconciliation, and other services relate (see here for details)
  • Documentation mostly remains untouched with the creation of a new Roadmap page.
  • About OpenRefine is a new section to present the project. It will also replace the Community link in the header
    • Mission and Vision will be updated once we clarify it
    • OpenRefine History present the changes of the project name and governance style
    • Project Role and Governance redirects to the file in the main repo
    • Who use OpenRefine provide general statistics about OpenRefine usage (see here for details)
    • The Grants and funding page remains the same.
  • Community become Links, and the link to the main github repo is moved here

As always, feedback and suggestions are welcome. I do not plan to implement those proposed changes right away. This week, I will move my attention to the Contributor Patwhays and Operation manual part.

1 Like

Hmm, just a small comment, but, I'm not sure its necessarily better that we have "more hiding" of Community links rather than pushing those up more visibly? Someone on the forum recently stated that they just found out the mailing list was changed into our forums and had to poke around to find the forum link? Dunno, maybe a one-off issue?

If I look at Links it's basically Social + just GitHub?
Hmm, maybe move Links call it Social and place it directly into nav header next to About?


@thadguidry I will update the sketch based on your feedback.

  • We can add the forum link to the header next to Donate and Github
  • OK to rename Links to Social

I created ticket #291, #292, and #293 for each workbook

1 Like

For the OpenRefine Ecosystem page, I am exploring using a (mind)map to represent the different entities and ecosystem organization. The graph is built using Mermaid, so it can be edited by anyone directly via Github.

I have attached a PNG export for your feedback (open in a new tab to enlarge it). I would like to enhance how we distinguish between people, projects, and artifacts such as forums and repositories. With the help of Mermaid, we can add links from one node to any webpage. I plan to use this feature to redirect to the extension page, for example.

At this stage, I am looking for feedback on the following point

  • Does the graphic make sense (do you understand it)
  • Is it too granular, not enough granular
  • Is it missing important information

The legend shows squares for orgs but your graph seems to use bubbles and also colors for orgs? Where does CS&S fit? Maybe it doesn’t need to here however.

Correct in this draft, the legend is not up to date. You can disregard it for now. It will be updated in the final version.

CS&S is located under the Advisory Committee under their full name (Code for Science and Society)

The CSCCE workshop ended last Friday and here is a summary of the where things stands. We already started to discuss specific point in separate Github issues or forum conversations, this post is to provide an overview on what's on my roadmap and in which order I want to approach them.

Playbook structure

The document Sandbox Playbooks presents the overall structure of the three playbooks and contains pointers to relevant discussion or existing documents. That document helped me step back and understand the different parts and how they relate to each other. I will keep using it as my blueprint as we make progress.

Overall we are looking at three playbooks, all hosted in OpenRefine/

Playbook 1: About OpenRefine

  • Target audience: General Public, Contributors, Partners
  • Goal: Increase Transparency regarding the project organization, governance, and roadmap.
  • Structure: Update the main website to provide a high-level overview of the project, including the project mission and vision, its history, roadmap, funding, OpenRefine ecosystem overview, and the project governance and roles

Playbook 2: Contributor Guides

  • Target audience: OpenRefine Contributors
  • Goals:
    • Increase Transparency: on how one can gain or lose access
    • Set norms and expectations regarding each role and how one can help
    • Help scale by helping new contributors onboard and grow as leaders.
    • Preserve knowledge: Document processes for the next generation of contributors.
  • Structure: Individual playbook for each contributor pathways: developer, designer, trainer, documentation, translation, user support, Code of conduct and Advisory Committee. I will continue to follow the existing structure with one subsection per contribution type under Contributing to OpenRefine

Playbook 3: Operation Manual

  • Target audience: OpenRefine Contributor and Staff
  • Goals:
    • Increase Transparency: on internal processes
    • Help scale and Preserve knowledge by providing a reference point
  • Structure: Create a new top section in our documentation or a sub-section in the Contributor Guide. It will focus on the what, how, and where for specific processes supporting multiple contributor guides using checklists and templates.

Deploying each playbook

I plan to deploy the three playbooks in five phases

1. Quick wins (March and April): I will draft PRs and submit them for review for the following section:

  • Restructure the website for pages that require little consensus:
    • OpenRefine Ecosystem
    • OpenRefine History
    • Who use OpenRefine
    • What's new (and release note)
  • Code of Conduct Contributor Guide
  • Advisory Committee Contributor Guide
  • Operation Manual: tools used (Github, Discourse, Figma, Zoom, SurveyMonkey, Email and Google Drive)

2. Clarify OpenRefine Mission, Vision, and Value (April to June). We are currently selecting consultants. A clear mission and vision will help structure the conversation for sections requiring community consensus in the following steps

3. Based on the new mission and vision (Summer 2024)

  • Update project roles and governance. This should be mostly cleaned up without major changes.
  • Project roadmap, how do we publish it, how do we agree on what's on the roadmap.
  • Social Conduct. I want to confirm first if we need it to complete the Code of Conduct.

4. Update or create the contributor guide based on the updated project roles and governance:

  • Developer: update existing content
  • Designer: update existing content
  • Translation: expand the guide
  • Support: create the guide
  • Trainer: create the guide
  • Documentation: expand the guide

5. I complete the operation manual separately including

  • Hiring and working with contractors
  • Grant Management
  • Applying to internship programs (GSoC, outreachy)
  • Maintenance on certain pages on the website.

I finally took the time to go through it all, and I like it!
Concerning governance, we can try documenting the current status-quo better but I'd be in favour of a bigger overhaul. Of course that requires larger community buy-in, and I am not sure how to do that given that the subject does not seem to attract so much interest.

The table you have started in your document is pretty similar to the one I came up with independently in Improving the onboarding process for new contributors - #5 by antonin_d. I guess we need to figure out how to make this discussion visible and interesting enough to get broader feedback.

Thank you for the review and feedback @antonin_d
I actually built the governance table based on the structure you outlined in the forum.

I think that the order of deployment that is outlined previously is important. For instance, the governance and roadmap are sensitive and critical components. To ensure a smoother process, I suggest that we first clarify where we want the project to go through the mission and vision, and then come to an agreement on how we work and communicate as a group via the values. Once these steps are complete, we can then proceed to open up discussions on these topics. Additionally, we should wait until we have agreed on the different project roles before writing detailed contributor guides.