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/openrefine.org. 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.

2 Likes

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 governance.md 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?

1 Like

@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
1 Like

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)