Documentation for modules

[jeffbowman]

I have created a docs/ folder with an org file and a generated info file for providing documentation.

Need help with documenting modules, see the docs/CONTRIBUTING.org. If you want to help, a PR is greatly appreciated!

craftedv2beta

Updated to the current focus (craftedv2beta)

• [x] crafted-completion (PR #331)
• [x] crafted-defaults (PR #345)
• [x] crafted-emacs-home (removed as of commit 5249c30)
• [x] crafted-evil (#344)
• [x] crafted-ide (PR #339)
• [x] crafted-lisp (PR #296)
• [x] crafted-org (PR #285)
• [x] crafted-osx (commit 928053072c1b434cc203829e3d44c69c213e02bc)
• [x] crafted-screencast (PR #303)
• [x] crafted-speedbar (PR #351)
• [x] crafted-startup (PR #341)
• [x] crafted-ui (PR #336)
• [x] crafted-updates (PR #340)
• [x] crafted-workspaces (PR #338)
• [x] crafted-writing (PR #329)

Note:

• crafted-init and crafted-early-init omitted as they are covered by the getting-started-guide.org file.
• crafted-package omitted as it's covered by the section on alternative package managers.

RC1

• [x] Transition Guide (PR #377)
• [x] Modules contributing guide (PR #384)

[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.

[jvdydev]

should we update the tracking for docs here (to crafted-, but also v2beta) or should we close this for a new issue?

[jeffbowman]

Probably should update this one to crafted- and for the modules in v2beta.

[jvdydev]

I'll update the original post if you don't mind

[jeffbowman]

I absolutely don't mind at all! :-)

[sthesing]

That reminds me of a question I wanted to ask. Since I'm writing a bunch of of docs at the moment, do you prefer them to be bundled in one PR (to avoid merging conflicts with the generated info file) or as separate PRs?

[jvdydev]

Probably separate PRs as it's easier to correlate each module docs with the respective module. At least that's how we've been doing it so far (and I don't really see a reason to change it).

Moving forward there will probably also be a better solution than manually generating the info buffer for each PR (maybe generating them in an Action as a post-merge commit?).

[sthesing]

maybe generating them in an Action as a post-merge commit?

Oh, that's possible? Cool, I didn't know that.

[jvdydev]

I might experiment with this when I get some time to tinker. It should be possible from my understanding (one can run actions post-merge with some trickery and committing to the repo shouldn't be an issue either).

[jeffbowman]

Could possibly be a GitHub Action as well, although I like the idea of a hook.

[sthesing]

OK, until such a solution is found, am I right in assuming that it's probably easiest to submit those PRs step by step so that I can regenerate the info files before each new PR? If yes, I'll wait until #331 is merged before submitting the next.

[jeffbowman]

Yes, for the moment, each PR should have its own regenerated info file (obviously making sure the appropriate pulls/merges occur to keep the branch up-to-date with the craftedv2beta branch).

[jeffbowman]

Closing after releasing V2