Skip to content

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

Draft
wants to merge 143 commits into
base: main
Choose a base branch
from
Draft

Wiki refurbishment #312

wants to merge 143 commits into from

Conversation

ronzulu
Copy link
Contributor

@ronzulu ronzulu commented Oct 28, 2024

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

@nriley
Copy link
Contributor

nriley commented Mar 1, 2025

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.

@ronzulu
Copy link
Contributor Author

ronzulu commented Mar 2, 2025

Sure, shall do...

@ronzulu
Copy link
Contributor Author

ronzulu commented Mar 7, 2025

I've added a new PR that includes the first part of the changes made here, hopefully easy enough to review :-)
Restructure part1 (focusing on the quickstart menu) #317

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants