Wiki Refactoring? [Discussion]

[C-Loftus]

I was interested in cleaning up some of the general formatting and structure of the wiki. I think for new users it is a bit overwhelming and https://github.com/TalonCommunity/Wiki/issues/99 brings up the same confusion I had when I originally started learning Talon a couple years ago, namely that the talon docs aren't really the docs for using talon via voice but rather how to script with it (both on the wiki and on the official site)

That being said, I sort of wanted to align before making any big changes.

To my knowledge, the current wiki also has some general UX challenges. It does not have anything like tags, dark theme, there are some visual challenges like the fact that the sidebar doesn't scroll down as you do, which makes the pages feel like super long blocks of text, and the search functionality doesn't show what text match but just the page name when searching. I think there are a fair amount of opportunities to make the documentation a bit easier to navigate and also easier to maintain. Long term down the road there isn't a good solution for localization either.

I was wondering if there were any opinions if anything some fundamental should be refactored? If we use an upstream static site generator and an established visual theme, then we don't have to worry as much about these UI/UX challenges and can focus more on just the content. However I wasn't sure how attached we are to prose.io, since I I am not sure how to migrate that)

There are a lot of options but each has a downside so I wasn't entirely sure. Hence, wanting to align

• docusaurus seems very good , easy to configure, but can also be extended if we need more advanced features in the future. It is slower than jekyll to build though and more bloated with dependencies (although it is very actively maintained)
• vuepress is nice but it seems harder to configure unless people know vue
• hugo or jekyll both have some challenges with their wiki themes and the current git-wiki theme seems to lack some of the UX features mentioned above.

• mdbook Is super easy to use but probably not appropriate since I don't think we really want a book but more so a wiki like format

  Let me know what you think I would be happy to take the initiative on this refactoring if we agree on something. No worries if not since I know any refactoring can be a pain

[splondike]

A paraphrasing to check I follow your thinking: the current wiki is a bit hard to use for new users, partially because of its information architecture, and partially from a lack in some features (search/tagging, UI layout, flexibility of static site generator). You're interested in improving those features and would do this by replacing the static site generator. You also bring up the prose.io editor.

I'm not particularly attached to Jekyll or the current UI. I also don't think prose.io is doing too much for us; we don't get too many contributors to the wiki, and I suspect most of them have a reasonable knowledge of Github. We could possibly get more contributors with a non-Git/markdown based editor; but then we'd have different issues.

I'd be happy if you wanted to look into prototyping a better option and uploading a .zip here with the contents or something like that for people to look at. A couple of thoughts about choice of software:

• The site's currently hosted on Netlify which I believe also does the builds. I don't know if that constrains anything. Since the wiki was set up Github released Github Actions, so we could probably swap to that if necessary.
• The Cursorless docs look like they're doing docusaurus: https://www.cursorless.org/docs/ . This is the other main documentation project in the ecosystem (aside from the community repo) so it would be nice to use the same system as that if possible so people can easily work on both. Search on the Cursorless docs is a SaaS provider; I don't know how that gets paid for. I think Emily pays for everything about talon.wiki currently.

[C-Loftus]

Yup your paraphrase is indeed what I am thinking.

We could possibly get more contributors with a non-Git/markdown based editor; but then we'd have different issues.

Yeah I was thinking about Media Wiki but then hosting becomes much more work intensive.

Cursorless docs look like they're doing docusaurus

Indeed. I recently made a PR against that and it is quite easy to demo locally. Just npm install; npm start and that's it to run locally. Only change I would make sure to do is to use a different theme than the cursorless docs so it doesn't look too similar and mix people up.

Searching and cost

Docusaurus has multiple free options for search https://docusaurus.io/docs/search Other than the domain name, there should not be any costs associated with this switch. I am not familiar with what other services Netlify does for this repo since the actions are private. Perhaps Emily could comment on this.

prototyping a better option and uploading a .zip here with the contents or something like

I am happy to do this, perhaps @2shea and/or Aegis (i.e. anyone that would have strong opinions on this) could comment on this to make sure this is reasonable before starting to go through testing, and then I can create a WIP PR branch. I think that is more efficient than zipping and sending.

[2shea]

Thank you for looking into some deeper refactoring and opening up this thread for discussion! I'm happy to see some momentum to improve the wiki!

I'm just getting back from some travels and caring for an ill family member, but I will respond with some thoughts in the next few days after I've been able to catch up on a few things.

[C-Loftus]

While we are at it, the current About section on the main page of the repo says Wiki for Talon beta. Should we change this? Was the wiki previously just for beta docs?

[C-Loftus]

@2shea No rush on this, but just wanted to bump this in case you had any thoughts. Had some good discussion at the Cursorless meetup today on this and it seems that others are on board with this idea externally

[2shea]

I was interested in cleaning up some of the general formatting and structure of the wiki. I think for new users it is a bit overwhelming and https://github.com/TalonCommunity/Wiki/issues/99 brings up the same confusion I had when I originally started learning Talon a couple years ago, namely that the talon docs aren't really the docs for using talon via voice but rather how to script with it (both on the wiki and on the official site)

This is a good point. The wiki to date has focuses more on the scripting. Earlier on when folks needed to write more of their own modules, that was more applicable. Now that the talon hub set is more filled out, many folks aren't looking to script, but are looking to understand how to use Talon. I support modifying the wiki to better meet the current needs of users today by including more docs around usage (vs. scripting/customization).

To my knowledge, the current wiki also has some general UX challenges. It does not have anything like tags, dark theme, there are some visual challenges like the fact that the sidebar doesn't scroll down as you do, which makes the pages feel like super long blocks of text, and the search functionality doesn't show what text match but just the page name when searching. I think there are a fair amount of opportunities to make the documentation a bit easier to navigate and also easier to maintain. Long term down the road there isn't a good solution for localization either.

I agree that the current wiki has UX challenges. The past couple months I've explored trying to swap out the theme to something better, but I've had a hard time finding a Jekyll theme that felt like enough of an improvement. Many Jekyll themes are optimized for blogging, and I've had a hard time finding a good theme for documentation without needing to do a lot of modifications.

I was wondering if there were any opinions if anything some fundamental should be refactored? If we use an upstream static site generator and an established visual theme, then we don't have to worry as much about these UI/UX challenges and can focus more on just the content. However I wasn't sure how attached we are to prose.io, since I I am not sure how to migrate that)

I am not attached to prose.io, and in fact, I have been wanting to remove it. At the time the wiki was built, we had some users who were not savvy with Ruby environments but wanted to contribute. I chose the theme with prose.io to accommodate the contributors at the time. Today we have only had one person use prose.io in the past year. The next most recent usage was a whole year prior to that. So, it's not heavily used, and IMO can be removed.

Also, the original wiki used GitHub pages, but I switched the hosting to use Netlify a couple years ago so we could have branch previews. With the branch previews, this gave users a way to view their changes without setting up a local Ruby environment, though not sure how many folks found this useful in that way. I've found the branch previews very helpful myself, though, both for working on my own PR's and reviewing others' PR's.

Docusaurus looks great from a quick review! I like that it's built for documentation specifically; I look forward to not fighting with a tool that really wants to be for blogging 👍 I do see that Docusarus can be hosted on Netlify if we want to continue with that. I do like the branch previews, but I imagine other hosting solutions support that as well.

[2shea]

I will take a look at https://github.com/TalonCommunity/Wiki/pull/236 and take a look at it locally 👀

If it helps move things along, I'd be happy to jump on a video call at some point.

[2shea]

Docusaurus has multiple free options for search https://docusaurus.io/docs/search Other than the domain name, there should not be any costs associated with this switch. I am not familiar with what other services Netlify does for this repo since the actions are private. Perhaps Emily could comment on this.

The Netlify account we are using is free. The only thing I'm paying for is the domain.

[2shea]

My wishlist for a refactor:

• Better search
• Branch previews
• No additional hosting costs
• Better navbar design and TOC sidebar responsiveness (i.e., scrolls as scrolling through the page)

[C-Loftus]

Thanks for your comments! Feel free to message me on slack if you'd like to do a brief phone call either now or before merging.

My only main question: Do you want me to do all deployment/docusaurus changes in one PR, merge that, and then do content refactoring after? Or do it all in one big refactor? First is probably better to track right?

Re wishlist

• Better search: Will add
• Branch previews: I say we probably keep Netlify if you want this. Github pages is easier for contributors to interact with, but yeah we don't
• No additional hosting costs: Definitely won't be an issue
• Better navbar design and TOC sidebar responsiveness (i.e., scrolls as scrolling through the page): Should be already implemented in docusaurus

[2shea]

My only main question: Do you want me to do all deployment/docusaurus changes in one PR, merge that, and then do content refactoring after? Or do it all in one big refactor? First is probably better to track right?

Yes, first option seems better to me. Smaller PRs 👍

[C-Loftus]

Closing since mainly addressed now