Documentation for users distributed, partly hard to read

[christofmuc]

@Andy2No I think I could produce both, the md version we have right now (which, when downloaded and viewed locally, is very useable!), and a csv version for easy import into Google Docs or Excel if somebody wants to work with the document.

Originally posted by @christofmuc in https://github.com/christofmuc/KnobKraft-orm/issues/208#issuecomment-1435986999

[christofmuc]

We currently have several parts of user documentation, that is potentially hard to find or hard to read:

• The download/build instructions. Those are prominent in the github README and most people seem to be fine with them.
• The adaptation programming guide. It is normally found, but you have to search for it as we do not point to it prominently.
• The user manual. This is not published yet, as I just started on it last year and then forgot about it. This will need some nicer place.
• The adaptation implementation overview. Hard to find, and harder to read. Useful as a reference to anybody trying to build an adaptation.
• Synth specific instructions. We have the Wiki page linked to by the adpatation page, but there is not much activity. The advantage is that it is a self-growing page easy to edit by everybody with a github account.
• Most information is buried in issue tickets, and some in discussion tickets. I thought of creating an FAQ, but honestly most questions are still genuine and not frequently asked. Still, there is gold mine of information in there that could be worth harvesting.

Many bigger OpenSource projects have their own Project page going beyond a simple github README, maybe we're at a point where this makes sense for us. What tools are there, are they all on github pages?

[bboc]

Most projects I know are on GH pages, because that's the simplest way for setting up a webpage and keeping it in sync with code changes, since a GH page is basically a collection of MD files in a dedicated folder (see setup instructions.

I recommend adding a command to the makefile that takes care of building anything related to documentation, e.g. the table for the adaptation's capabilities.

As for content, I find the readme too large, simply because there is no way of knowing what's in there without browsing il. A couple of links at the top to the sections would help, of course. But once you have those links, they later might as well point to the documentation pages, and then a readme that contains a short explanation, a screenshot and the license might be enough.

If you want to preserve the wiki, just link to it from the list of adaptation. I'm not so sure the wiki will grow much, though, because I expect that once a certain feature set and number of adaptations is available, most users will not have a GH account anyway. So maybe a collection of doc pages for adaptations is enough. Since the wiki is basically a GH page, and it has a separate repo, you can clone it and copy the pages over to the new GH page.

I have some experience in setting up GH pages, so I might be able to help you with that if you wish.

[christofmuc]

This looks interesting, might be overpowered: https://docs.gitbook.com/

This is a node based generator which seems sensible as well: https://vitepress.vuejs.org/guide/configuration

[christofmuc]

Looks quite sensible: https://vitepress.vuejs.org/guide/deploying#github-pages

Everything is there, docs would be written in a directory full of markdown files. Some of them could be generated.

This looks nice and very lightweight: https://docsify.js.org/#/?id=docsify

There is probably a migration path regarding the generator once we decided to use GH pages and markdown. That ecosystem seems to be quite rich in tools.

Sphinx would use rst files. I probably feel more comfortable in md.

So for long term support, something like gitbook.com is bad because they might just go out of business or close down public repos or what ever. The docsify javascript action is probably most robust, because you have apart from that javascript no other dependencies that can go out of date.

I'd probably start off with docsify, and if that turns out to have bad performance we can switch to a site generator like vitepress or any other...

[bboc]

I wouldn't recommend rst if you want other people to contribute to the documentation, Markdown is much simpler and much more widely used these days.

What would you see as added benefit of docsify or vitepress over plain github pages? Jekyll is a pretty powerful site generator, here's one example of a github page that uses a responsive and free theme that might cover all your needs.

[christofmuc]

Ah ok, I though Jekyll to be more heavyweight. I need to read the docs and understand how I can use it, I have no experience with it.

[mslinn]

I use Jekyll, and have written many plugins https://www.mslinn.com/jekyll/index.html

Although I prefer HTML, Jekyll can work with markdown and/or HTML files