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.
I wanted to give you an update on my progress with revising the handbook. The last week I focuses on two aspects
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)
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.
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?
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)
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.
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.
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
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.
