Open danyill opened 1 year ago
I generally agree with everything you write here, and have some additional thoughts on the following points:
- 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).
- 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.
- 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.
@ca-d and Tamas will start with initial technical documentation.
Update: The two of us never got started on doing this, maybe other work took priority.
Requirements: Common format Standardized format Fetch documentation form multiple locations
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).
I'm going to do some prototyping on Asciidoc/Antora in the next few weeks as I need a solution for user-facing documentation.
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:
Requirements
Other requirements
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.