RFC: new home for 'Learn Plover' tutorials?

[Zack Brown]

Hi everybody,

I originally wrote the 'Learn Plover' tutorials on Google Sites, as an easy web-hosting solution.

https://sites.google.com/site/learnplover/

Gradually a few people in the plover community asked for 'write permission', which I happily granted. But it's become clear that 'Learn Plover' should really be a fully community-maintained and open-sourced site, and not something that is only for a few people to control.

I haven't been very involved in plover for the past several years, and so I've been comfortable to kick the can down the road, make fixes when someone reported a bug, but otherwise not deal with the issue. But now, Google is changing the whole Google Sites feature into something that doesn't support the formatting I use to identify keypresses. They're forcing Sites users to 'upgrade', and so it's not really realistic to stick with the status quo anymore. What other changes might be forced on Sites users in the future?

So I'd like to hear suggestions about what should be done with the site.

It seems like 'Learn Plover' is still a valuable resource. Maybe it should be incorporated into the github repository with the plover source code, and be viewed entirely on github? Maybe it should be converted to a 'real' HTML site with JavaScript and all the trimmings, and hosted on a community-run server?

Tim G has already volunteered to help with some of the HTML/CSS/JS stuff (and his interest partly inspired this RFC), and maybe other people would like to volunteer too? Is it possible we could put together a team that would each offer part of the software/hardware that would be needed to migrate away from Google Sites?

What are your thoughts? What does the Plover community want from 'Learn Plover'? Where should it go and how should it get there?

Be well,

Zack

[Ant]

Heya,

Thanks for writing the original Learn Plover!

I'd love to help with this project, and can do some front-end web and hosting stuff if needed. Another possibility is making it less like GitHub, and more like wikibooks — so there's not a group of admins who has to approve each change, and people who aren't used to GitHub can feel more comfortable contributing.

[Til Blechschmidt]

I definitely agree that putting it out there for others to contribute would be beneficial. Regarding hosting, I'd recommend using a GitHub Repository with Github Pages (https://pages.github.com) as it is free and can be integrated directly with the "source" files. Storing images and other media in the repository is definitely possible too. It makes it easy for others to contribute but also for other people to extend it (I've recently hacked together a tool which scrapes the Google Site and creates a somewhat usable E-Book to read on my Kindle — perfect candidate for a contribution).

For formatting, something "common" like Markdown is most likely the best as it allows easy contribution and conversion into a multitude of formats (e.g. EPUB). Concerning special formatting: AFAIK you are using bold, monospaced, and inverted text on a dark background. Bold and monospace are supported by default in Markdown and "highlighted" text should definitely be possible with one of the many "common" extensions (e.g. some ==marked== text). When converting to HTML, adding a few custom CSS rules to style it in your preferred way should be rather simple.

Speaking of conversion and special CSS, static page builders like https://www.11ty.dev or https://astro.build come to mind.

[Ted Morin]

While writing Art of Chording, VuePress has been a really nice tool. Others that I looked at were Gatsby and Docusaurus. Both seem like they'd fit the bill if you can get a developer who has a little bit of React or Vue experience.

With GitHub Actions, building the code and deploying it to GitHub Pages is easy, fast, and free. If I were doing this project, I would move it to a GitHub repo and convert to one of the tools above then invite the maintainers to the GitHub repository.

The only concern with moving to a GitHub repository that I see is maintaining an open source project is hard work and there are certain expectations with fielding issues and pull requests, so whoever takes over should be ready to deal with that or explain in the readme what contributions are acceptable and which aren't.

Best of luck,

[James Laird-Smith]

In the R community, we have developed a very successful solution through a tool called bookdown.

bookdown is based on R Markdown, which is a document format that is similar to Markdown.  It's very easy to read and contribute to. It's allowed the R community a wonderful freedom of collaboration on a slew of books, with people suggesting everything from typo corrections to entire section re-writes. You may need to know a bit of R to set it up from scratch. But you don't need to know any R to contribute. I would be easy to maintain.

But R Markdown is also a collection of engines (primarily relying on Pandoc) that allow you to export your content to PDF, LaTeX, HTML, EPUB, and Word etc. bookdown would control how the components are rendered in the various formats.

For HTML output, the default engine is GitBook, but there's also built-in support for Bootstrap and Tufte. Hosting is usually very easy with either Github pages or Netlify.

I'd be happy to put together a skeleton of what it would look like? And people could try it out and see if it worked for them? But I wouldn't be available to maintain it full time or migrate the content.

[Alab with a b Liang]

I'd be interested in maintaining the website, but I can't make any promises on actual plover knowledge.

[Ant]

I know this thread has talked about GitHub a lot, but I'd like to push the idea of using a wiki like wikibooks. There's some popular books on there already, like Blender 3D: Noob to Pro or Non-Programmer's Tutorial for Python 3.

The advantage is that it's like a wiki where anyone can add their contributions, unlike GitHub which may require a few admins to authorise pull requests etc., which can be a lot of work, and has a higher barrier to entry for people who want to contribute (there have been a few people in the discord channel who have been hesitant about contributing on GitHub). The disadvantage is that there's less control over formatting, but the current Learn Plover! site doesn't seem to have anything complicated, so there shouldn't be any problems with the site as it is. If we did want to have more control, we could set up our own wiki, for example on Miraheze (which allows you to set custom CSS, have your own domain, etc.), or through self-hosting.

I'd be happy to start migrating content to wikibooks if people like the idea of a wiki rather than GitHub?