Add a link to OR’s CLI in the Automating section #391
Conversation
Adding in automated section a link to OR’s CLI from Felix Lohmeier.
✅ Deploy Preview for openrefine-website ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Wouldn't it be better to remove mentions of all these unsupported clients, since they could be considered implicit endorsements? They are using an undocumented, unsupported, and, most importantly, untested internal protocol which has very limited error handling/reporting (because it's designed to be used in a restricted web client with user supervision). |
|
@tfmorris I think we do a good job in the prior 2 paragraphs of explaining caveats, and "not responsible" attitudes well enough? No? But perhaps you'd like to suggest something additional into those paragraphs to make it more clear "not an endorsement", and "undocumented, untested, internal protocol used with limited error handling"? |
@tfmorris: I think they should go to a different page. Personally, I would had another section, like “External tools and services”, and there, I would do a page for the clients (the section I’m modifying now), a subsection or a page for all the extentions, and a subsection/page for the Reconciliations Services. They would all benefit from more explanation for the purpose, installation, usage, etc. Regards, Antoine |
|
@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? @magdmartin 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 team from maintenance pain? |
|
In my opinion the existing warning is already pretty scary, I don't see a need to deter people from using those tools even more than what we currently do. I also think we should re-evaluate this policy of discouraging people from using the HTTP API externally. The HTTP API is legitimately used by our own extensions - as seen with the issue created by removing CORS support from the get-rows command. It's difficult for me to understand why we'd decide to be so conservative for changes to Java classes (everything being part of the stable API, even the most obscure classes) and have no stability to offer on the frontend side. |
|
Ah, regarding the API, @wetneb that's actually a really good point and agree. |
|
Should the documentation page redirect to our current listing on the main website: https://openrefine.org/extensions#client-libraries? This would avoid maintaining a list in two different places. We could also reproduce the warning on that page. Those libraries are actively used. The preliminary results of the 2024 user survey show that about 7% of our users rely on one of those libraries (16 out of 226). |
|
@magdmartin Agree, I'd suggest we move that small listing and caution under Automation. "Running" is just not semantically the same as "Using it with...(i.e. automating, etc.)". That would leave the Automation section on All in favor? |
@magdmartin : why should the documentation about tools, extensions and services be out of our current documentation? What’s the advantage for a user to have to look at 2 different places? That why I’m proposing to had a third section in our documentation. Here’s the link to the forum discussion about that: Improving the documentation with a new section, “External tools and Services” Regards, Antoine |
Adding in Automating section a link to OR’s CLI from Felix Lohmeier.