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?

[ttkorhonen]

I think the result looks good. I have also been trying to learn rst and readthedocs; for instance "rst-ifying" the CA reference manual in my sandbox. Results can be seen here and the git source here. I had to reformat one nested table differently to make it render properly but otherwise this was rather straightforward. I did not find the nested table very useful in the first place. On the other hand, I really like the new editor (Gutenberg) in the EPICS website now. Making a small change is even simpler than with the readthedocs flow (IMO). I guess we need to figure out some criteria on what should go to the website and what to readthedocs.

[anjohnson]

The formatting looks really nice, but I'm not quite sure about the overall structure. Many of those pages are independent, stand-alone documents, and for them to have "Next" and "Prev" links at the bottom seems a little strange, especially ones that point across major sections. For some pages it does make sense though, the Collaboration Meeting link goes to a 2-level section where the individual pages all fit into the same topic, and there I do want Next and Prev links. If there was more content under Common Database patterns I would suggest splitting each pattern into its own page (with Next/Prev between them), but for now putting them all on a single page is fine.

On the top page under "Indices and tables" the "Module Index" link points into 404-land.

Most of the texts do need updating — I guess that's what the Codeathon is for!

[ttkorhonen]

I think that this was meant to be a demo of what it could look like rather than a final solution. The "next" and "prev" can be removed if wanted and the structure reworked as needed. But as always, there has to be somebody who takes care of the structure. Anyway, if this looks like a good way to go, then I would like to ask the Documentathon participants to spend a little bit of time to learn RST and the readthedocs tools (including Sphinx etc) as a preparation. The we can speed up the start a bit.