Revamp / cleanup of OpenRefine's Wikibase documentation

trnstlntk commented 2 years ago

OpenRefine started off with Wikidata support, and is now also increasingly supporting arbitrary Wikibases and now also Wikimedia Commons (yay!)

This is great, but our Wikibase documentation is still structured as a remnant of the old Wikidata-centric situation. Wikibase documentation has been added over time in various places, and in OpenRefine/OpenRefine#5023 I shoehorned in some documentation focused on Wikimedia Commons. But as a whole, IMO the documentation has become a bit inconsistent and potentially confusing for end users. I think it would be great to dedicate some time to a future-proof re-edit of that entire section.

Proposed solution

Fresh reorganization of the Wikibase support section. Some of my thoughts here:

I think it's good to often explicitly mention both Wikibase, Wikidata, and Wikimedia Commons. Wikidatans and Wikimedia Commons users may not be familiar with the term 'Wikibase' at all.
I have a hunch that we are mostly serving three distinct groups of users with this documentation: Wikibase users, Wikidatans, Wikimedia Commons editors. This may need a bit more research and testing, but I think it does make sense to provide various entry points if these are indeed large distinct groups (even if the back-end features, and the Wikibase extension as a whole, are considered as a holistic architecture from the technical side).

Additional context

Maybe we can fit this into the upcoming Wikibase-focused work (roughly July-December 2022) which will be funded by NFDI.

trnstlntk commented 1 year ago

Fresh reorganization of the Wikibase support section. Some of my thoughts here:

I think it's good to often explicitly mention both Wikibase, Wikidata, and Wikimedia Commons. Wikidatans and Wikimedia Commons users may not be familiar with the term 'Wikibase' at all.

I have a hunch that we are mostly serving three distinct groups of users with this documentation: Wikibase users, Wikidatans, Wikimedia Commons editors. This may need a bit more research and testing, but I think it does make sense to provide various entry points if these are indeed large distinct groups (even if the back-end features, and the Wikibase extension as a whole, are considered as a holistic architecture from the technical side).

Additional context

Maybe we can fit this into the upcoming Wikibase-focused work (roughly July-December 2022) which will be funded by NFDI.

@lozanaross confirmed that she'd like to see the revamp happen in this direction, and that it will be good to do it as part of the 2022 NFDI grant. We're on the same page here. I intend to work on this in the upcoming months.

I may also do further tweaks throughout 2022-23 as part of developing dedicated training materials for Wikimedians using OpenRefine (50K grant funded by the Wikimedia Foundation).

trnstlntk commented 1 year ago

The three user communities (Wikidata, Wikibase, Wikimedia Commons) see themselves generally as separate from each other, and I will look into revamping our documentation roughly as follows:

The current header Wikidata, Wikibase, Wikimedia Commons in https://docs.openrefine.org/ will become three headers.

First header: Wikidata
Second header: Wikibase: with Wikibase-specific additions and 'specialties'; including sections dedicated to settings to be installed / tweaked by Wikibase maintainers
Third header: Wikimedia Commons: section that documents Wikimedia Commons-specific additional features

trnstlntk commented 1 year ago

I have gotten started on this. There's a lot of information to process!

As a general basis for writing good documentation, I first familiarized myself with the Diátaxis framework for software documentation, which is used by many projects (internally and for public-facing documentation). Thanks to @jdittrich for the tip! The Diátaxis framework distinguishes between four types of documentation:

Tutorials
How-to guides
Reference
Explanation

@wetneb told me that OpenRefine's manual at https://docs.openrefine.org is mainly built as a reference manual (and I agree that that's a sensible approach). I.e. OpenRefine's documentation is designed to be a 'dry' overview of features offered by the software.

Specific tutorials and how-tos are already actively created by OpenRefine's many / diverse user communities. I think it's good to embrace and further encourage this, linking to good resources out there from OpenRefine's own (reference) manual. For instance, I have created how-tos for Wikimedia Commons editing and batch uploading, which live on Wikimedia Commons. We also have an external how-to (probably not fully up to date anymore) on establishing a data upload pipeline in a Wikibase with OpenRefine, created by @lozanaross on Wikiversity.

Going forward, I think I will simplify OpenRefine's Wikibase/Wikidata/Commons documentation further with the above in mind, possibly removing some 'how-to' style sections and replacing them with more 'dry' reference. Still keeping in mind that the Wikidata, Wikibase and Wikimedia Commons communities are three distinct communities and the reference sections should be discoverable by each of them. It's possible that I will move some 'how-to' materials elsewhere.

For my own sanity (?) I am keeping track of all topics to be covered in a spreadsheet - work in progress: https://docs.google.com/spreadsheets/d/1FED2dep0yKCGR9FFfuW5VGXNul4Q01fSBDWb-gg3Qvc/edit#gid=0

OpenRefine / openrefine.org