-
Notifications
You must be signed in to change notification settings - Fork 83
Wiki refurbishment #312
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Wiki refurbishment #312
Conversation
for more information, see https://pre-commit.ci
…e end of `directiveContainer`
…b.com/ronzulu/talon-community-wiki into issue-170-improve-for-non-programmers
… flowchart using mermaid
Thank you for updating your changes! Unfortunately this PR is now so large that it is essentially impossible to review. Would you be able to split your changes into a few separate PRs? Feel free to start with just one and we can figure out the right granularity. |
Sure, shall do... |
I've added a new PR that includes the first part of the changes made here, hopefully easy enough to review :-) |
Hello
Talon is great, and the community is awesome in helping users with issues, but as a newcomer, I found the documentation not all that beginner friendly.
From comments on slack, I see that this isn't just me and I've taken it upon myself to overhaul the wiki. I hope I haven't stepped on anyone's toes, and I know that it may not be adopted, but I thought that it is worth a short.
The aims have been to:
1. Incorporate all material from the community README
Incorporate from https://github.com/talonhub/community/blob/main/README.md,
so that the README would for the most part be a pointer to the wiki.
As a newcomer it is difficult to know what to glean from the wiki and what to learn from the README, especially as they cover overlapping topics. Hopefully not offending anyone, but given how comprehensive Talon is, I don't think that having documentation in a long single page README is all that suitable.
IMHO only information relevant to those building or maintaining the community file set should remain there, such as the sections on contributing and automated testing.
2. Make the documentation more beginner friendly
Sometimes this it's just simple wording changes, for example from "essential integrations" to "popular integrations". ("essential" can freak out a beginner as if taken literally means installing and learning about seven integrations)
Separate out Talon programming related info from beginner level topics. For example, the first paragraph on the page about talon lists https://talon.wiki/Customization/talon_lists says ".talon-list files do exactly the same things as a Python Context". Something confusing for anyone other than a programmer.
In this case these details were moved to a separate section called "notes for programmers"
3. Include all user relevant commands that are missing
Some user relevant commands have been missing from the wiki and also from the README as well.
For example, "clone line" or "go up" is missing. There is a reference in the README, but (unless I've missed something) a user would need to read through edit.talon to find these useful commands.
4. Restructuring
I've done a moderate amount of restructuring, I hope this is okay!
5. Feedback
I think this is 80 or 90% complete, but before I do any more I wanted to know if it is liked and if the community elders will want to adopt it.
If so, then I will incorporate feedback and complete tidying it up.
Cheers
Ronny