Improving the documentation with a new section, “External tools and Services”

Community OpenRefine documentation
1

I would like to have more available informations on the external tools, clients and services (particularly the Reconciliation services, except Wikidate/wikibase/Wikimedia Commons).

A new section for that would make it easillier to write and display more information.

Is this something other people would like to see/use?

Regards, Antoine

2

Copying my reply from your PR about this:

@Antoine2711 Just throwing this out there, but... for things outside the control of OpenRefine, perhaps another alternative of where that information could be posted or captured into would be Wikibooks or Wikiversity articles?

@Martin and I had discussed places where the community might begin doing those sorts of things, like writing up things about OpenRefine and its ecosystem. Rather than us hosting a Wiki ourselves to allow the community to use, I felt that Wikibooks (textbooks or manuals) or Wikiversity (manuals or training resources, articles) might be better and save our small team from maintenance pain?

3

@Antoine2711, we have the pages Extensions | OpenRefine and Other distributions | OpenRefine on the website. They are somewhat up to date, though we may have missed the latest extension developed by @thadguidry. Is this what you were looking for?

@thadguidry To maintain a single conversation thread, I will respond in the PR #391

1 Like
4

Yes @Martin, We have a full page with tables for list of extensions, list of tools and list of Recon servers. But…

  1. It’s on the Web server of OR, not in the documentation. It’s not visible and easy to find.
  2. It’s just lists. What I propose is a single page for each of these tools, extensions and reconciliation services.
  3. The tables in that page only have a small descripion of the tools/services/extensions. It doesn’t help when you don’t understand really SNAC, FAIR, etc.
  4. We cannot, as OpenRefine contributors, easily update each of these tools’ documentation. And for each release, there are probably details to update for many of theses, or even screen snapshot to update. I know for myself, I wouldn’t go in these tools documentation to update them. But I would if it was in our documentation.
  5. Even for the Extension page on the server, it’s harder to update it than for our documentation page. Also, I believe that few people should have the right to update our web server, whereas for documentation, it should be less restricted.

I could go on, but I guess making things much easier for understanding, installing, using these tools/services would make OpenRefine much more user friendly.

Regards, Antoine

1 Like
5

I really don’t want to create another place for these documentations. I beleive these are things that should be easy to find, and one place with all that information goes a long way. Not to mention the need to learn different tools, just to have a better documentation for OpenRefine.

I also believe those tools are what makes OpenRefine powerful, and I wouldn’t use OpenRefine without a few of them.

Regards, Antoine

6

Thanks, @Antoine2711, for clarifying your thoughts. I agree that the discoverability of existing extensions and reconciliation endpoints can be improved. We previously discussed the interest in creating an extension/reconciliation management interface within OpenRefine to let users discover and install them.

I am not sure if we should try to document those extensions ourselves rather than relying on what the developer already provides. While I see the benefit for the user to have everything centralized, I am particularly concerned about the duplication of the documentation (what already exists and what will be available in OpenRefine documentation) and the increase of scope of what we would need to maintain.

In conducting a quick survey of how other projects address this, I don't see a specific pattern emerging.

7

I understand the problem of the duplication. Really. And I hate it.
But the reality is that OpenRefine changes MUCH MORE often than the tools/extensions. And as such, we often need to ajust the way we configure/install/use those tools/extensions.

Most of the documentation of these tool are minimal, as they are usually coders and programers that write them for themselves, and as you know/understand, the documentation of a open source project is more often the poor child, as the programers don’t think like user, a non-technical person.

I know that, even after using OR for 6 years, I often struggle to use/install those tools, maybe because I don’t use them very often, and I don’t really understand them thoroughly.

The way I see it, is that, as a power user who understand coding and technicalities, if I have a hard time, then, most of our users must also.

For me, if I take the time to install/tryout those tools on Mac/Windows/Linux, I’m willing to document that work when I do it, so that, if I come back 6 month later, I can have good information to do it again. But I know that if I have to talk/interact with all those different organization, I will just document it for me in personal docs.

If it was easy, like the current docs we have, I would rather share them. Its also a motivation to do better documentation, as I know many people will benefit from it.

Regards, Antoine

8

@Antoine2711

  • I guess my stance is that external extensions are not "OpenRefine".
  • And your stance is that, external extensions/tools are still part of "OpenRefine ecosystem" and if the community is actually volunteering to keep things up to date, than we should give them some space under /docs to do that.

In that regard, we are in agreement. :tada: :+1:
So the next question is... where do we give them that space? :interrobang:

:white_check_mark: Your suggestion is quite valid, I guess, to keep things centralised if we aren't doing the updating, but the community will. That usually means something like a Wiki. But you'd rather keep things centralised, with better folder hierarchy (sorta what we did with the old Wiki on GitHub), where extensions and tools could be fully listed and described on their own pages in Docusaurus. And the cost is $0 for us financially. The labor cost is $0 for us. The benefits to the community are likely :100: and so...

:+1: I am OK with that suggestion.

2 Likes
9

I am aligned with @thadguidry, and I am in favor of hosting more documentation on GitHub - OpenRefine/openrefine.org: Source website for openrefine.org regarding extensions.

I suggest updating Writing extensions | OpenRefine to invite new extension developer to create a page in our documentation presenting their extensions.

2 Likes