Documentation for modules

[systemcrafters]

Documentation for modules

[sthesing]

I'm working on documentation for rational-completion. I have two questions regarding which I could use opinions or advice:

1. My current approach is to explain what each of the used packages does by stacking them on top of each other and describe how it changes Emacs' behaviour: how does hitting "M-x" and typing "buf swi " behave in a fresh install, with vertico, with vertico+orderless, with vertico+orderless+marginalia and so on...
   I think that should demonstrate both the specifics of each package as well as how they work together. Can you folks think of any reason not to do it like that?
2. In the org-file, I'd like to include screenshots of the changing behaviour, which obviously won't make it into the info files generated from it. I'll write the text so that it makes sense with or without the screenshots. Is that OK or do the org and info versions of the documentation have to be absolutely identical?

[jeffbowman]

My original intention with the org files was to make it easier to get people to contribute as it is more commonly known than is the texinfo markup. I never even considered it might be used to host things like screenshots of examples since the point was to use org export to generate the info files.

That's a pretty neat idea, then not only can the user read the docs from inside Emacs, but can come back to this repo and see the screenshots! Nice! You might need to mark the screenshots with noexport, but I'm not 100% sure since I haven't tried to export screenshots to info.

Regarding (1), I think your approach is fantastic, so I'm looking forward to your work. It might be possible to use ascii drawing mode to put together "screnshots" in info to demonstrate how vertico, vertico+orderless, vertico+orderless+maringalia are working. Just an idea though.