Unified smart macro documentation

[mondalaci]

@kareltucek Currently, the documentation is scattered across doc, doc-dev/reference-manual.md, and doc-dev/user-guide.md. We should make them accessible from a central place and possibly unify them.

I'm unsure about the specifics, but as for the UI, I'm confident that a sidebar would work well for navigation, just as for the QMK and Kaleidoscope documentation.

We should discuss this further. Do you have any specific ideas?

[kareltucek]

Currently, the documentation is scattered across doc, doc-dev/reference-manual.md, and doc-dev/user-guide.md. We should make them accessible from a central place and possibly unify them.

It is split this way intentionally. User guide is meant to a an easy introduction that teaches the reader how to combine the constructs, while reference manual serves as an exhaustive reference.

Please note that the reference manual is designed to be searched (ideally via Ctrl+f, not via a google-like feature), so splitting it up into a number of small articles would hurt the usability.

Do you have any specific ideas?

Nope.

[mondalaci]

We can keep the reference manual and user guide separate. As a matter of fact, it'd be a mistake to merge the documents, as it'd result in a single huge document. It'd rather make sense to make them accessible from a central place via a menu. The documents would still stay searchable via Ctrl+F.

How about transitioning from markdown to HTML eventually? That way, we could place interactive widgets into the documentation that'd include code to the current macro command.

[kareltucek]

Well... I am definitely not a fan of HTML, but it may make sense for some articles.

On the other hand, for instance GitHub markdown allows HTML, so that might be a way forward too if the docs platform supports some similar notation.

Generally I think that we should provide core documentation in a format that is robust and is not likely to break down and become unreadable and unbuildable once some technology goes out of fashion. (In my opinion, html with javascript and npm magic is one of those technologies. Agent is a great example of how npm stuff can break down if it is left unmaintained for mere months.)

[kareltucek]

(Closed accidentally.)

[kareltucek]

Tho bottom line is that we should probably carry on with your idea and see where it takes us, and maintain current markdown docs alongside. If things go smooth, the markdown docs will get phased out naturally, and may remain just as a backup for future generations, or get removed if it turns out that the new docs can be trusted to survive on their own if left unmaintained...

[mondalaci]

The GitHub Flavored Markdown spec is quite a beast, and it seems to me that it supports some limited set of HTML, but I'd think it has severe limitations when it comes to fancy features like interactive widgets.

One can argue that some npm modules can go out of fashion, but the ones we use are very popular and widely used, so I wouldn't worry about them.

It may be trivial to convert GitHub markdown to HTML with Jekyll if we choose to do it.

Regardless of the source format we use, I envision a Vue.js based single-page application that contains all the documentation we have. The sidebar would allow navigation between the pages and sections of pages and search for any content immediately without page reloads.

A good first step would be to take all three documents we have and assemble them according to the above. @ert78gb and I can take care of this, as it's a web development task.

The user guide and reference manual are well-named titles, but I'm unsure about the title of the HTML documentation. The current "Smart macro reference" title sounds redundant when put next to the already existing "Reference manual". Maybe this will be a non-issue eventually as we restructure the documentation, though.

[kareltucek]

A good first step would be to take all three documents we have and assemble them according to the above. @ert78gb and I can take care of this, as it's a web development task.

Yes please. Let me know if you wish me to write some new texts or edit the existing ones.

The current "Smart macro reference" title sounds redundant when put next to the already existing "Reference manual".

Feel free to rename it. For instance "Command reference", "Command description", and "Exhaustive list of commands" come to mind.

But generally, I think that redundancy in titles is not a bad thing and can be hard to avoid.

[likern]

Well... I am definitely not a fan of HTML, but it may make sense for some articles.

On the other hand, for instance GitHub markdown allows HTML, so that might be a way forward too if the docs platform supports some similar notation.

Generally I think that we should provide core documentation in a format that is robust and is not likely to break down and become unreadable and unbuildable once some technology goes out of fashion. (In my opinion, html with javascript and npm magic is one of those technologies. Agent is a great example of how npm stuff can break down if it is left unmaintained for mere months.)

https://typst.app

Open source, modern alternative to LaTex, can render into pdf (very stable format). I think later it will support rendering into html (or svg) format