Increasing participation from designers โ€“ update on the Outreachy design internship and more

Hi everyone,

This post will combine a few interrelated topics: 1) update on the documentation coming out of the design project with our Outreachy intern @Lydiaofficial; 2) some ideas for general restructuring of the Documentation section of the website with a view on highlighting contribution how-tos (related also to this topic); and 3) some recommendations for the general OpenRefine website, which we received from our consultation with designers from

  1. @Lydiaofficial has been busy over the last few weeks on cleaning up the design system documentation in Figma (more on that soon) and preparing a document for how designers can contribute to the project that can be inserted in the Documentation space on OpenRefine's website. The draft document is here: Design contributions Doc - Google Docs So far it includes a short intro and a ToC, which Lydia will work to fill out this week & next. Any input on the general structure and if we're missing any important points is welcome!

  2. In order to fit this dedicated 'contributions for designers' doc in an appropriate place on the public OpenRefine documentation site, I'd like to propose the following slight overall restructuring.

Current structure:

  • User manual
  • Grel reference
  • Technical reference
    ** Contributing to OpenRefine
    ** Architecture
    ** Extensions
    ** Maintaining OpenRefine

New structure:

  • User manual
  • Grel reference
  • Technical reference
    ** Architecture
    ** Extensions
    ** Maintaining OpenRefine
  • Contributing to OpenRefine
    ** As a developer
    ** As a designer
    ** As a user

The idea of this new structure is to bring out contributing more prominently and allow a new sub-structure depending on the type of contributor.

  1. Talking to Jan Diettrich and Django Scorupa from the open source design community last Friday, we got positive feedback on our approach so far, with Jan committing to support the editing and final review of text for the document shared in 1) above, and with Django volunteering to support the final version of the design system documentation in Figma.

Speaking to them about the placement of the documentation within the overall OpenRefine site, they pointed out that to recruit more designers onto the project two important aspects need to be addressed:

  • Making it obvious who are the users of this project and why we (designers) should be excited about helping these users. A simple and elegant solution here would be to feature at least 3 use case studies on the main homepage - either above or below the 'main features' section; eg case study with data journalism; with science data; and with GLAM data. The case studies themselves can be shown as cards (similar to the main features) which upon click open to new pages with short texts and 1-2 images. It would be particularly impressive if we can include some logos of major institutions using OR, either within the case studies, or just as a separate mini section on the homepage, I've seen this on other OSS projects - it just lends legitimacy and makes it more desirable to be part of the team, if like the National Libraries of such and such country are using this, or this and that major journalistic outfit, etc.
  • Making it more easy to directly jump to the 'how to contribute' sections in the documentation part of the site. It's great we have the 'Get involved' link in the footer, but it could be make more prominent with a direct call to action within the content area of the homepage. Just an example of one OSS project that has nice sectioning on the homepage is this: (but there are loads of other good examples, too).

All feedback welcome!


I love all of your work on this, Lozana, and will share it in the Wikimedia Foundation's design channel too. The Wikimedia movement could also do more to invite designers in.


Thanks for the update! Your proposed structure makes sense to me, in fact we have very recently done a step in that direction by separating the contributing page into separate pages for different contributor profiles: Split contributing page into role-specific subpages by wetneb ยท Pull Request #233 ยท OpenRefine/ ยท GitHub. A lot more work can go into improving the contents of those pages of course. In particular the one for designers, which should eventually link to (or include) the design system documentation, I assume?

I intend to do a bit of work on the pages about translations and documentation contributions (which are currently mixed up with content written for developers), but I'm holding off the design one.

Showcasing concrete use cases from the landing page would also make a lot of sense to me - I think the Google Refine videos did a pretty good job at that, so it'd be great to have a more up to date equivalent (not necessarily in video form).

Speaking of increasing participation from non-developers, I have been trying to think of ways to include them better on GitHub, where a lot of important discussions are currently happening, and I wonder if you'd find those instructions useful to that end? The goal is that more people are able to rely on GitHub notifications (via email if they rarely visit the platform) to stay in the loop for discussions that matter to them. The preview is here:

You can add your feedback on the associated PR.

I would suggest putting the Users first under "Contributing to OpenRefine," similar to what I suggested here:


Thanks @antonin_d - yes, the idea is that the doc above linked in my post above is going to replace the complete current section about contributions from designers.

What would be the best way to proceed? To create a new branch, structure all the new .md files we want to be the different sections of the designer contribution part, adjust the sidebar structure in the .js file and then do pull request for review? I'd like @Lydiaofficial to do the branch & set up the .md files this upcoming week if possible as its her final official week of the internship. We can of course extend the review process beyond that, but at least she'll get the experience of going through the set up process.

Sounds good - happy if user contribution instructions go first, then it can be for devs & then designers. I don't mind the order as long as all contribution docs are pulled out of the technical reference section and given their own more prominent spot in the sidebar table of contents.