Question about Documentation Generation, Up-to-Date Information, Binder-Friendly Cheatsheets, & a Potential Book

[jasheb]

Hi everyone,

First off, I want to reiterate how inspirational I find the Cursorless project. Your work is truly appreciated!

I've been looking at the available documentation, and I see there are "cheatsheets." These seem to be along the lines of what I was thinking about in terms of a concise command reference. However, I'm curious about how these are generated.

Could you shed some light on whether the Cursorless documentation, specifically these cheatsheets, is automatically generated from the source code? The ideal scenario, in my mind, would be an architectural setup where the command lists and potentially keyword shortcuts are embedded within the source code itself, allowing for automatic generation and rebuilding of documentation (like printable PDFs) whenever the codebase changes.

On a related note, could you also confirm if the main Cursorless documentation is currently up to date? It would be incredibly helpful to know that the information we're relying on reflects the latest state of the project. Sometimes with these kinds of projects, it can be unclear whether the documentation accurately represents the current functionality.

Finally, are the existing cheatsheets designed with printing and use in a binder in mind? Knowing if they are formatted for easy printing would be really useful for those of us who prefer a physical reference.

On a slightly different note, I've come to understand that Cursorless is quite powerful and almost a language in itself. I would personally be very interested in purchasing a comprehensive, custom-made book about Cursorless on Amazon if the core team were willing and able to create one and make it available for sale. I believe there would be a market for such a resource.

Understanding the documentation generation process, the currentness of the main documentation, the intended use of the cheatsheets, and the potential for a more in-depth book would be really valuable.

Thanks!

[AndreasArvidsson]

Hi!

Thank you. We really appreciate it!

Most of the documentation is manually written markdown files, but there is markdown with embedded react components. For example the language files is in this category. They use structured data in typescript to generate what's implemented in each language. When it comes to the cheatsheet if you invoke it with a voice command all the spoken forms are your customized grammar. The one on the webpage uses Cursorless default spoken forms. The cheatsheet is generated from source code and utilizes the actual list of actions, scopes etc so that part is automatically kept up to date. Some of the more complex descriptions in the cheatsheet is manually crafted though. So its a combination.

We definitely make an effort to keep the documentation up to date, but I can't promise that there isn't a single sentence that hasn't rotted over time. I can say that the documentation reflects the current state of the project to our best effort.

The cheatsheet is just a webpage. Definitely a lot of people have printed it, but it's not built specifically to fit in a single standard page or something like that.

Releasing a book would be amazing. For now I'm just hoping to get some free time to do a few more youtube videos. Actually writing a book is quite unlikely while I have a full time job in addition to Cursorless, Talon community etc. Interesting idea though! :)

Finally I would like to say that contributions to the documentation would be appreciated.