12:55 PM (12 minutes ago)
to openrefine-dev
I intend to have a go at restructuring and improving the technical
documentation on the website (in an effort to keep migrating out of the
wiki), so it could have its place there.
Github is the central developer location (aka "hub") with the source code, issue tracker, CI dashboard, etc.
Why would you move core development process documentation to a separate place?
Tom
12:56 PM (12 minutes ago)
to me
Message blocked
Your message to openrefine-dev@googlegroups.com has been blocked. See technical details below for more information.
The response was:
The group openrefine-dev@googlegroups.com does not allow posting through email.
When we set up the user manual on Docusaurus, it felt like there was also a consensus to migrate the technical documentation there as well. It definitely did not get as much love as the user manual, and I feel responsible for improving that. So I did not really question the fact that it would happen on Docusaurus as well. But I have no strong feeling about it.
I am overall not a fan of the GitHub wiki, for the following reasons:
- poor searchability
- crimped design (by enforcing a fixed width)
- hard to keep the pages in a consistent, structured hierarchy (there is a side bar which attempts to provide structure but it is not visible on all pages - not sure why)
- less formatting options than on Docusaurus (for instance, offering the ability to show instructions for a given operating system throughout the page)
But that being said I like the fact that the wiki can be edited easily, without having to open a pull request.
For me the core documentation should make newcomers to the project feel that it is easy to get started both running the software and contributing.
Obviously the quality of the content is a huge part of this but I also think it should be well organised, easy to access and look professional (which is clearly subjective but I do think the look of the documentation is a factor in making newcomers feel they are joining a well run project)
For me the current Docusaurus powered site works better for these aims than the GitHub wiki. While a wiki is obviously meant to lower barriers for contributing the flip side of this is that the documentation grows in a rather haphazard manner and also the GitHub implementation of a wiki leaves much to be desired. For example the reason that the menu structure doesn’t appear for all wiki pages is that to use this aspect of the GitHub wiki you have to follow a file system structure and as soon as you create a file outside the structure it breaks this navigation. (this is based on my previous experience trying to organise the GitHub wiki more - if the process has improved since then I’m happy to revisit this)
But I also think having a more formalised mechanism of contributing to the documentation allows for more quality control and organisation. In this sense having to make a PR to contribute to the documentation that can then be reviewed offers a quality control mechanism (although I think GitHub wiki can also be configured to require PRs it slightly undermines the wiki aspect)
I don’t agree that just because we have issue management and code on GitHub we need to use it for the documentation as well - plenty of projects don’t do this and I think a separation of concerns allows for both flexibility and us to adopt the most appropriate solution for a particular part of the project - for example while there’s no expectation of this right now we might decide at some point that GitHub is no longer the best place to host code and/or issues (this has happened in the history of the project once already of course) and separation of concerns here could easily be an advantage if that were to happen.
[So apparently my posts are being moderated on this list despite the fact that I was an owner of the previous list. How many of the other moderators got dropped? We'll see how long this post takes to get approved.]
The developer documentation is terrible because it's ignored, not because it's not pretty. Moving away from the easy editability will further discourage contributors.
I am overall not a fan of the GitHub wiki, for the following reasons:
I think it's great that I can do a single search across the project's code, issues, and wiki pages. If the wiki page that I land on needs tweaking, I can edit it right there. I wonder why search is characterized as "poor."
With a split scheme, unless I'm misunderstanding it, the developers will need to do two different searches and, if they have a minor doc change to make, find the site repo, do another search to find the right page, make the edit in their fork, submit a PR with the change, wait who knows how long for the PR to be reviewed, fix the review comments, wait for another review cycle and, hopefully, merge, before their improvement goes live.
But that being said I like the fact that the wiki can be edited easily, without having to open a pull request.
Yes, exactly. That's one of the key benefits of a wiki.
Tom
About the searchability of the GitHub wiki: here is why I find it inconvenient.
When browsing the wiki, there is no obvious search field associated with the wiki. It is not obvious to me that the search box in the top GitHub bar can be used for that. And even then, when you use it, you first land on a page where the first results are often from the code base. You need to refine the search to the wiki only, adding another step.
In some cases, that behaviour of mixing up issues, code and wiki pages can be desirable, but for someone just looking to get started with contributing, I find this a bit convoluted.
On the over hand, the contribution process to make a change in the Docusaurus-based documentation should normally be much simpler than what you describe. On each documentation page, there is a link to GitHub which can be used directly to make edits to the page. The fork creation is (if I am not wrong) also taken care of by that UI, so the user does not need to do it explicitly. The main overhead that is left is the need to describe the changes by providing a PR title and body, and indeed the reviewing time.
Since we have already initiated this move to Docusaurus I would still be inclined to finish it up. I think one other advantage of this new platform is that it is more motivating for me to write good content there, alongside the new user manual, because it feels like a more visible and modern place.
My dream would be to have proper onboarding documentation like the one Zulip offers.