Improve online help/documentation and developer documentation

[danyill]

Is your feature request related to a problem? Please describe.

As a user of OpenSCD I need clear and accessible documentation. Our current documentation while bundled within the app is not easy to read, find and navigate information.

ca-d mentioned:

Regarding the Help, I think it'll be useful to update the wiki, but I'd really like to fix the help viewer (internal links currently do not work) before updating the content again. Currently the built in help viewer is hardly usable to me.

My current favored solution for fixing this bug:

1. Introduce a build step which compiles the markdown to static HTML files into the distribution directory.
2. Get rid of the markdown renderer runtime dependency.
3. Render the static html help statically into an iframe in an editor type plugin using import.meta.url to construct the iframe's original src attribute.
4. ???
5. Profit!

Requirements

1. I like building documentation and including it in the distribution.
2. I think it would be better to integrate a dedicated static site generator to do this and then be able to link to it from OpenSCD.
3. This allows a separation of orthogonal concerns.
4. I am not sure this should be integrated within an editor plugin. I prefer it not to be so that help can be within a separate window and not block other user activity (as currently, in OpenSCD, only one editor can be open).
5. I think it's important to ensure that the current extensibility and plugin development in open-scd-core doesn't mean that documentation, accessibility and installation become too fragmented across a glorious future open-scd ecosystem.
6. I think this implies:
   • Documentation can be brought in from different sources
   • It may imply the ability to mix and match documentation (core, plugins, perhaps collections of plugins, including vendor or manufacturer-specific plugins).
7. I think using an SSG which is designed to meet these concerns would help.
8. I am somewhat opinionated about this and have a preference for Asciidoc and Antora (rather than Markdown).
   • Antora supports distributed documentation which is one of its key strengths and Asciidoc has a stronger feature set for technical writing than what-ever-your-favourite-flavour-of-Markdown. It is widely used for instance in OpenSUSE, Fedora and Red Hat docs for example. Demo sites list here.
   • Plus Asciidoc was originally invented by a New Zealander :stuck_out_tongue_winking_eye:

Other requirements

1. Ability to integrate help and documentation from different plugins
2. Ability to generate offline search without internet (Antora supports Lunr for instance).
3. Ability to integrate, as required, different media and perhaps adjust documentation for the absence of an internet connection (i.e. drop video content, for example).
4. Mobile-friendly views.

I'd be happy to do some work on this if there was interest in using Asciidoc/Antora, both of which I'm familiar/capable with. Specifically, I volunteer to figure out the integration within the open-scd build (perhaps once the new core is migrated to) and convert the existing documentation.

[ca-d]

I generally agree with everything you write here, and have some additional thoughts on the following points:

4. I am not sure this should be integrated within an editor plugin. I prefer it not to be so that help can be within a separate window and not block other user activity (as currently, in OpenSCD, only one editor can be open).

I like this idea! Having a menu plugin that just opens the help in a new window doesn't preclude having an iframe-based help browser in a separate tab in addition (e.g. for phones and tablets which don't view more than one window at a time anyway and often have cumbersome browser tab navigation controls).

5. I think it's important to ensure that the current extensibility and plugin development in open-scd-core doesn't mean that documentation, accessibility and installation become too fragmented across a glorious future open-scd ecosystem.
6. I think this implies: ...

I completely agree! I therefore suggest delivering a compiled version of our OpenSCD distribution wiki (the future successor of our current open-scd github project wiki) along with a "open in new window" menu plugin (and possibly a viewer plugin for the differently browsered community) in the OpenSCD distribution itself. Other distributions may use a fork or just include our content in their build toolchain for their own help plugin. This way other sources can be integrated at the last possible moment: distribution build time.

I am somewhat opinionated about this and have a preference for Asciidoc and Antora (rather than Markdown).

• Antora supports distributed documentation which is one of its key strengths and Asciidoc has a stronger feature set for technical writing than what-ever-your-favourite-flavour-of-Markdown. It is widely used for instance in OpenSUSE, Fedora and Red Hat docs for example. Demo sites list here.
• Plus Asciidoc was originally invented by a New Zealander :stuck_out_tongue_winking_eye:

I'm not that opinionated - we've used markdown so far only because it's the default for github wiki content. Luckily, github wiki seems to fully support Asciidoc, so there shouldn't be anything in the way of our already migrating our wiki to that syntax. The surprising point raised about the format's provenance is the first substantial argument I find this clearly in its favor after my recent experience with Kiwi work ethic. I'm therefore enthusiastically convinced.

Should one help plugin's desire be to specifically compile any number of documents in any number of formats (LaTeX, .doc, .pdf, Asciidoc, .rtf, and the like) into a cohesive whole, I would suggest having a look at https://pandoc.org/ for the conversion and unification effort.

[Sander3003]

@ca-d and Tamas will start with initial technical documentation.

[ca-d]

Update: The two of us never got started on doing this, maybe other work took priority.

[Sander3003]

Requirements: Common format Standardized format Fetch documentation form multiple locations

[trusz]

We discussed the topic. Currently it is not urgent but we would like to slowly progress it. As a next step we need to find out if there is anything AsciiDoc provides that we cannot solve with the current document format (markdown).

[danyill]

I'm going to do some prototyping on Asciidoc/Antora in the next few weeks as I need a solution for user-facing documentation.