Closed C-Loftus closed 3 days ago
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:
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?
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.
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.
Yup you are right. I think gifs are good too.
Closed since I think the docs are improved since this was opened.
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
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. Themodel 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 usingmodel $PROMPT
and not applying targets or destinations.We have a few options
Use a docs as code approach
.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.Create a simple website describing the grammar more fully
model
is required, but[{user.modelSource}]
is not when speaking a command)npm
installedIt 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.