Make initial documentation more end-user friendly

[Eeems]

We've now heard from several users that the documentation we have for toltec doesn't make it easy to understand for end-users who are not technical what toltec even does.

[koenvervloesem]

I have always found https://brew.sh a concise but clear homepage documenting the basic use of this package manager. Especially the section "What Does Homebrew Do?" This could be some inspiration for more user-oriented documentation.

[LinusCDE]

I have always found https://brew.sh a concise but clear homepage documenting the basic use of this package manager. Especially the section "What Does Homebrew Do?" This could be some inspiration for more user-oriented documentation.

I had thought about adding some kind of rendering markdown docs in a static site generator, but only have a little bit of experience in hugo and I'm not sure whether I can find the time. Maybe having a website-style site like brew (maybe in the style of our current repo-view) would be cool. More advanced topics could then just link to github again while giving most users everything they need.

[matteodelabre]

Agreed. I propose we make a user-friendly homepage at https://toltec-dev.org (instead of redirecting it to the README) and save the developer-focused instructions for the repo README. Some topics for the homepage:

• Purpose
• How to install (including OS-specific instructions for how to connect to the device through SSH)
• How to use (via the command line or via Nao)
• Link to the packages listing
• Q&A (Can this brick my device? Is this supported by reMarkable AS? Where can I get help?)

Some more advanced topics to save for the README only:

• Who maintains Toltec
• Link to the Discord community
• Contributions
• Stable/testing workflow
• How to build the packages manually

If anyone can think of other useful topics, please add them below!

[raisjn]

do people prefer markdown + static site generator? (jekyll is pre-included with github, for example) or static HTML?

[koenvervloesem]

Markdown and a static site generator seems more maintainable: you can reuse/include parts of the docs in the repo then.

[matteodelabre]

Writing HTML by hand can get tedious quickly, but since we’re starting with only one page it could be a reasonable option. I personally find that Markdown is a bit limiting and suffers from the lack of an official spec. I prefer alternatives like reStructuredText or AsciiDoc in that regards (supported by the Pelican static site generator or by Jekyll through plugins, for example).

[raisjn]

i'm partial to jekyll + it's markdown since it's included with github. it's also easy to make a two column layout in it, for example:

``` # Toltec #### A software repository for the reMarkable tablet

---

## Install Toltec $ wget http://toltec-dev.org/bootstrap $ echo "cbe83d1ae2d3ef6291a2b57202bb59aace14f2f1849bbdb09552a7419995294a bootstrap" | sha256sum -c $ bash bootstrap {: pre} To automatically install Toltec, run the bootstrap script in a SSH session on your reMarkable {: .left} This script installs the toltec package repository and related tools. {: .right} ## What does Toltec do? Toltec is a repository of homebrew applications for the remarkable tablet, similar to homebrew for Mac or linux package repositories. {: .left} $ opkg install nao {: pre .right} ## How to use the `opkg` command is used to add/remove/update packages. [see our quickstart guide]() {: .left} $ opkg update $ opkg upgrade {: pre .right} ### [See all the packages available](https://toltec-dev.org/stable) ## Frequently Asked Questions * Do you support remarkable2? Yes, but you need to install the rm2fb package if you want to use any applications that use the display. * How do I contribute to toltec? See [the contributing doc]() * Will this brick my remarkable? No ```

[koenvervloesem]

That's actually not bad, really nice! In general I also prefer the power and semantic purity of reStructuredText, but for this purpose Markdown seems perfectly fine.

[raisjn]

i'm trying it in rst too

[LinusCDE]

That looks pretty cool indeed. Haven't played with this sw before but it seems really similar to remark. I've used that to make a simple presentation on the spot and it worked beautifully. Having a simple markdown or rst basis that can be juiced up with custom css is the great in my opinion.

[raisjn]

doing it in rst isn't too bad either - i like that specifying css class comes before a section instead of after, but links are more awkward than in kramdown.

index.rst

``` ====== Toltec ====== A software repository for the reMarkable tablet ----------------------------------------------- Install Toltec ============== :: $ wget http://toltec-dev.org/bootstrap $ echo "cbe83d1ae2d3ef6291a2b57202bb59aace14f2f1849bbdb09552a7419995294a bootstrap" | sha256sum -c $ bash bootstrap .. class:: left To automatically install Toltec, run the bootstrap script in a SSH session on your reMarkable .. class:: right This script installs the toltec package repository and `related tools <#>`_. What does Toltec do? ==================== .. class:: left Toltec is a repository of homebrew applications for the remarkable tablet, similar to homebrew for Mac or linux package repositories. .. class:: right :: $ opkg install nao How to use ========== .. class:: left the `opkg` command is used to add/remove/update packages. `see our quickstart guide <#>`_ .. class:: right :: $ opkg update $ opkg upgrade --------------------------------------------------------------- Frequently Asked Questions ========================== * Where can I see all the packages available? at https://toltec-dev.org/stable * Do you support remarkable2? Yes, but you need to install the rm2fb package if you want to use any applications that use the display. * How do I contribute to toltec? See `the contributing doc <#>`_ * Will this brick my remarkable? No ```

toltec.css

``` .left, .right { display: inline-block; width: 49%; padding: inherit 0; margin-left: 0.5%; vertical-align: text-top; } h1, h2, h3, h4, h5 { text-align: center; } pre { padding: 10px 0; background-color: #ddd; overflow: auto; } body { background-color: #f8fcf8; margin: 0 auto; padding: 20px; max-width: 1024px; } ```

build with rst2html --stylesheet-path=toltec.css index.rst > index.html

EDIT: put this code into a pull request: https://github.com/toltec-dev/toltec/pull/193