Improve Documentation

[C-Loftus]

Currently this repo, like many others in the talon ecosystem, has a discoverability challenge. Most users want to quickly understand commands and not need to reference .talon files. The model help command is a good start, but does not describe the whole grammar. As such, based on usage patterns in the public forks, it seems that people are just using model $PROMPT and not applying targets or destinations.

We have a few options

• Use a docs as code approach

  • talondoc doesn't support .talon-list files so I don't think it is the proper choice at the moment. I am also just not much of a fan of readthedocs and it is better for API reference imo, not documentation.
  • We could autogenerate docs locally but we can't do that in CI since talon doesn't run in CI

• Create a simple website describing the grammar more fully

  • Thinking of having a horizontal row of drop down menus. Each menu contains all the options for that particular part of the grammar. Each menu drop down would be labeled if that part of the grammar is required or optional. (i.e. model is required, but [{user.modelSource}] is not when speaking a command)
  • Could use any JS framework, or even vanilla JS. We just want something that would compile to a static site such that it can be hosted on github pages, or ran locally without npm installed
  • We probably still want to template the final page in some capacity, so we can pass in the list of prompts dynamically from talon and not need to worry about hard coding all of them.
  • We probably want to have a page for any talon settings, lists, and tags that affect this repo.
    • This is mainly described in the readme's but people are probably not referencing those much

• It would be nice to have a quick tutorial. So having a sample use case and all the commands a user would need to do to accomplish it

• We could also just use Docusaurus for all of this like the talon wiki or Cursorless docs does, but I feel that is overkill. I would like to ship the site in this repo and have it be easy to template or create custom interactive docs, even if it is less feature rich.

Open to other ideas if anyone has a preferred strategy. We don't need to implement all of the above all at once. We have a lot of cool functionality in this repo and I want to make it easier for new users to discover and use.

[jaresty]

based on usage patterns in the public forks, it seems that people are just using model $PROMPT and not applying targets or destinations

While I do think it is objectively a good idea to focus on having good documentation, I think it is difficult to draw a strong conclusion based on the usage patterns in public forks:

1. It is not a requirement in this repository to make a fork to use it
2. Those who have forked the repo are not necessarily using it regularly
3. The usage patterns of people whether they're using a fork or not is opaque since we aren't tracking people

I think that one of the best ways to see and learn how to use talon in community and elsewhere is to have videos demonstrating how people use it. I sometimes tried to publish videos of my usage patterns in #demos in the talon community slack but I could do it more often. The main thing that prevents me from doing it more is that I'm working on proprietary things and can't share that.

I like the ideas here for improving the documentation. One question that I have is how we will know if the documentation improvements have been successful-I don't think that looking at the forks is going to be very useful for answering that question. Maybe we can use a poll or something like that?

[C-Loftus]

Yes I agree that patterns in forks are not ideal data but I think it's the best we have. Either way, I don't have any indication that anyone is using the more complicated commands. So I think the main goals for this would be not just documenting but also trying to improve discoverability. The lack of issues posted here is probably a good sign frankly, but it also means that people are probably not exploring / tinkering much. Thats just my best guess.

[jaresty]

I think some demonstration videos could go a long way. The other day I was pairing with someone and I used 'model blend' in his reaction was 'wow'. A lot of these commands are much better seen and understood that way than to read about.

[C-Loftus]

Yup you are right. I think gifs are good too.

[C-Loftus]

Closed since I think the docs are improved since this was opened.

[C-Loftus]

That being said we could still use some gifs or better helpers (i.e. drop downs to dynamically see the grammar of a valid command) but that is out of scope for this issue probably