Collaborative documentation on the website

[keijokorhonen]

The way we allow users to collaborate on the website currently, is a little too complicated and confusing to users. Users are forced to find the relevant page from the massive sea of pages and then assign a parent page, add it to the documentation index. The move to Gutenberg has simplified editing a page a lot, but I believe we should simplify the process by at least making a separate section for documentation in the Wordpress dashboard.

We could always use a plugin, as there are many Knowledge Base plugins out there. From what I've seen though, the good ones all seem to cost and are sold on a third-party website. This gives me flashbacks to a certain theme we used and could end up as a Power Builder v2.

I would suggest using readthedocs.org as its well supported and has great collaboration features. It looks like it's possible to use the design for our purpose, short and unrelated articles/instructions. All documentation can be hosted on GitHub, which would make the process of contributing even easier.

Would love to hear your opinions on this.

[ralphlange]

The link in your comment does not work.

I like readthedocs.org, but I only know it as a host for generated documentation.
What do you see as a workflow for manually generated pages?

[keijokorhonen]

We would use a Github repository containing all the documentation and configurations like e.g. the Godot engine docs. Users can first write their articles in Markdown, then submit pull requests for edits or new pages, which have to be approved by a repository administrator. When the master branch receives a new commit, readthedocs will then clone the git repository and update the documentation website.

I'm sorry I don't quite understand what you mean by manually generated pages/generated documentation. The documentation would still be written by people, all that would change is the format in which it is written, where it is hosted and how it looks to end users.

[ralphlange]

With manually generated, I mean: actually typed word by word by a human.
I know how to push Doxygen generated or Javadoc pages to readthedocs. These are generated as part of building a software project.

[ralphlange]

Ok, understood.

I support this approach. Using PRs on GitHub for contributions seems like a widely-known procedure that is well-suited for our audience.

Does this setup support test-builds of PRs to be able to review suggested changes without having to have a full sphinx setup and compile locally?

[keijokorhonen]

This setup supports versioning, so that we don't have to merge pull requests to the master branch to be able to see changes. Since the files are written in Markdown, we can also see the suggested changes in the Github preview.

[ralphlange]

Have a look at https://docs.readthedocs.io/en/stable/subprojects.html
This is how our things could be organized. A custom domain (e.g. docs.epics-controls.org) and Javadoc, Doxygen as well as the hand-written parts as subprojects.

Btw. Please reST instead of Markdown.

[ralphlange]

@shroffk - would that fit with the doc ideas of the Java devs?

[ttkorhonen]

Re Markdown, good point. I was about to write about the looming religious fight, Markdown vs reST. I vote also for reST, maybe we can preempt the fight by setting a standard early.

[shroffk]

+1 for reST

[anjohnson]

For larger documents that will need things like tables of contents I agree that standard reST is a better choice than Markdown. I'm not convinced that a 3-paragraph HowTo with some quoted code quite falls into that category, but I won't try and change what appears to be a consensus by the rest of you. GitHub's rendering of rST only handles some aspects of the formatting though (e.g. see the table here or this page).

[ralphlange]

I agree for short documents without a lot of formatting. The difference between the two shouldn't be huge in those cases.
But how is GitHub's reST rendering relevant?

[anjohnson]

how is GitHub's reST rendering relevant?

Some contributors may use the editor built into GitHub (click the "edit this file" pencil towards the top right of a page you're viewing) which has a Preview tab that shows the rendered result. The Edit tab also has syntax highlighting enabled. Thus some people may adjust their edits so the results look good on GitHub without realizing that the final rendering could be a bit different. Editing the table I pointed to above highlights the :download: and :ref: keywords in red, but they were written to be processed by Sphinx and so may not be a good example.

[keijokorhonen]

I converted some of the pages found on the website to RST and played around with readthedocs a little. You can see the result here: https://epics-docs.readthedocs.io/en/latest/ and repo here: https://github.com/keijokorhonen/epics-docs.

Setting it up was very simple and it looks very readable. What do you think?