Openrefine: Setup repository for product documentation

[ostephens]

To better support OpenRefine we are undertaking a project to improve documentation. Documentation source files will live in a separate Github repo in the OpenRefine org, and from there be published to a documentation platform.

This issue is to setup the new repository

See https://docs.google.com/document/d/1VtzXjSqrliAp1R8Xy3yARXIiN5NuV0dNf4apvJz4rl8/edit# for more detail

[kushthedude]

@wetneb @ostephens Didn't we agree to put the documentation in the OpenRefine Repository itself? And to publish the website we can use an outsourcing script or script to generate docs dynamically from the given URL.
I think there is general agreement that the source of the docs should live in the same repository as the code (OpenRefine/OpenRefine), so that we can encourage contributors to update the docs as they change the behaviour of the tool.

To better support OpenRefine we are undertaking a project to improve documentation. Documentation source files will live in a separate Github repo in the OpenRefine org, and from there be published to a documentation platform.

[ostephens]

@kushthedude for the technical reference documentation we'll definitely be doing this - via javadocs. I think for the product reference documentation we need a separate repo. I think we can still encourage contributors to update the docs as they change behaviour of the tool.

(definitions of technical reference vs product reference given at https://docs.google.com/document/d/1VtzXjSqrliAp1R8Xy3yARXIiN5NuV0dNf4apvJz4rl8/edit#)

[wetneb]

Did we not also agree to store the source for the user manual in the main repository?

My understanding from the meeting we just had was that I would set up a repository to host GitHub Pages deployment for the docs, but the source of the docs would stay in the main repository.

[tfmorris]

One advantage to having a separate repo is that permissions can be managed separately from the main source code repo.

Also, re:

we can encourage contributors to update the docs as they change the behaviour of the tool

writing good quality code and writing good quality user documentation are two very different skill sets. It's not uncommon for people to have one or the other, but not both.

[wetneb]

About permissions, I am not really sure why we would want to grant a user access to the docs and not the code or conversely. Changes to both are done through pull requests anyway, the master branch is protected. If someone becomes disruptive in any area we can easily remove them. We are currently trying to invite contributors to the organization as soon as they start contributing, which lets them contribute to issue triage and become part of the team. I think this works pretty well so far. In my experience there is little risk that people start abusing permissions and start messing up in an area they don't know about.

writing good quality code and writing good quality user documentation are two very different skill sets. It's not uncommon for people to have one or the other, but not both.

That is true. I would actually expect two sorts of pull requests:

• PRs which only contribute to the docs, expanding / improving the docs in some areas;
• PRs which contribute to the code, and make the required updates to the docs, which should generally be quite minimal and not require a lot of creativity. For instance, if you are adding a new option to an importer, simply add a bullet point in the corresponding list in the docs, with two sentences explaining what the option does. You don't need to be good at writing documentation for that, it's just about imitating the rest of the page.

It's somewhat analogous to the Weblate integration: some people only contribute translations, and some others write code add the required messages when needed. It's useful to keep the two in the same repository because they evolve together.

[wetneb]

Closed by #2513. For now we are trying a monorepo approach, let's see if it is viable.