Draft
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
Contributor
|
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. |
Contributor
Author
|
Sure, shall do... |
Contributor
Author
|
I've added a new PR that includes the first part of the changes made here, hopefully easy enough to review :-) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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