Website: a project site with docs, how-tos and an FAQ #12

New Issue

2026-10-05T09:57:21Z

twisla commented

2026-10-05 09:57:21 +00:00

Idea

A dedicated website for roro9stack, separate from the blog and the Gitea repo. It would have:

what it is, with screenshots
how to install it
a user guide for each App
how-tos
an FAQ
developer docs
downloads

Why

The Gitea repo is aimed at developers, and the blog posts tell stories. Neither answers "how do I flash this, set up Wi-Fi and use the Gemini App?" A site makes the project usable by someone who isn't us.

What could be on it

Home: what roro9stack is, the hardware (Cardputer ADV and Cap LoRa-1262), screenshots, the latest version.
Install:
- Flash from the browser with ESP Web Tools (Web Serial, Chrome or Edge, an "Install" button with no toolchain needed), using the factory.bin from releases (#5).
- Or esptool by hand.
- Then first boot and Setup.
User guide, one page per App: Launcher, Settings (Wi-Fi, Storage, Firmware), IRC, Wi-Fi Tools, GNSS, Gemini. Later: SSH, Files and the others from this backlog. Each page covers the keys, the screens, and where things are stored on the card.
How-tos:
- Updating over Wi-Fi or from the SD card.
- Recovering with Safe Mode.
- Saving Gemini pages to read offline.
- Recording a GPX Track.
- Using a Debug Build and the Debug Console.
FAQ:
- Why is my position not shared?
- Why did a page stop loading?
- What does Probation mean?
- What happens when the card is full?
Developer docs:
- Building with Docker.
- The architecture (services, Apps, the event bus, StorageService's task).
- The glossary (CONTEXT.md), the ADRs and the milestones with their decisions.
- How to contribute.
Downloads and changelog: from Gitea releases (#5).
Blog: links to the roro9stack posts on experiments.twis.la.

What's known

The generator.
- Zola is already used for the blog, so its templates, shortcodes and the SVG diagram style could be reused.
- Docs-focused alternatives: mdBook, which is small, Rust-based and good for guides, or MkDocs Material, which has search and navigation out of the box.
Single source. The developer docs should be generated from the repo's docs/, CONTEXT.md and README, not copied. Otherwise they drift.
Screenshots are easy: the Debug Console's screenshot command, as used for the blog posts. A script could refresh them all for each release.
Hosting. On the same server as experiments.twis.la, for example roro9stack.twis.la. It could be built and published by CI once #5 exists.
A Gemini capsule. The same docs as gemtext, served over Gemini, readable in the device's own Gemini App. That fits the project, and the gemtext could be generated from the same Markdown.

Questions for the design round

Where does it live: in the firmware repo (site/, versioned with the code), or in a repo of its own?
Which generator: Zola, like the blog, or mdBook or MkDocs?
Which domain: roro9stack.twis.la, or something else?
Should it have the browser flasher (ESP Web Tools)? That needs releases from #5 and the CORS headers set on Gitea.
Docs per version (v0.5, v0.6…) or only for the latest?
Should there be a Gemini capsule mirror, and if so, should the gemtext be generated from the same source?
What language: English only, or French too?
Should the FAQ start from real questions, for example from issues tagged kind/docs?

## Idea A dedicated website for roro9stack, separate from the blog and the Gitea repo. It would have: - what it is, with screenshots - how to install it - a user guide for each App - how-tos - an FAQ - developer docs - downloads ## Why The Gitea repo is aimed at developers, and the blog posts tell stories. Neither answers "how do I flash this, set up Wi-Fi and use the Gemini App?" A site makes the project usable by someone who isn't us. ## What could be on it - **Home:** what roro9stack is, the hardware (Cardputer ADV and Cap LoRa-1262), screenshots, the latest version. - **Install:** - Flash from the browser with ESP Web Tools (Web Serial, Chrome or Edge, an "Install" button with no toolchain needed), using the `factory.bin` from releases (#5). - Or `esptool` by hand. - Then first boot and Setup. - **User guide, one page per App:** Launcher, Settings (Wi-Fi, Storage, Firmware), IRC, Wi-Fi Tools, GNSS, Gemini. Later: SSH, Files and the others from this backlog. Each page covers the keys, the screens, and where things are stored on the card. - **How-tos:** - Updating over Wi-Fi or from the SD card. - Recovering with Safe Mode. - Saving Gemini pages to read offline. - Recording a GPX Track. - Using a Debug Build and the Debug Console. - **FAQ:** - Why is my position not shared? - Why did a page stop loading? - What does Probation mean? - What happens when the card is full? - **Developer docs:** - Building with Docker. - The architecture (services, Apps, the event bus, StorageService's task). - The glossary (CONTEXT.md), the ADRs and the milestones with their decisions. - How to contribute. - **Downloads and changelog:** from Gitea releases (#5). - **Blog:** links to the roro9stack posts on experiments.twis.la. ## What's known - **The generator.** - Zola is already used for the blog, so its templates, shortcodes and the SVG diagram style could be reused. - Docs-focused alternatives: mdBook, which is small, Rust-based and good for guides, or MkDocs Material, which has search and navigation out of the box. - **Single source.** The developer docs should be generated from the repo's `docs/`, CONTEXT.md and README, not copied. Otherwise they drift. - **Screenshots** are easy: the Debug Console's `screenshot` command, as used for the blog posts. A script could refresh them all for each release. - **Hosting.** On the same server as experiments.twis.la, for example roro9stack.twis.la. It could be built and published by CI once #5 exists. - **A Gemini capsule.** The same docs as gemtext, served over Gemini, readable in the device's own Gemini App. That fits the project, and the gemtext could be generated from the same Markdown. ## Questions for the design round 1. Where does it live: in the firmware repo (`site/`, versioned with the code), or in a repo of its own? 2. Which generator: Zola, like the blog, or mdBook or MkDocs? 3. Which domain: roro9stack.twis.la, or something else? 4. Should it have the browser flasher (ESP Web Tools)? That needs releases from #5 and the CORS headers set on Gitea. 5. Docs per version (v0.5, v0.6…) or only for the latest? 6. Should there be a Gemini capsule mirror, and if so, should the gemtext be generated from the same source? 7. What language: English only, or French too? 8. Should the FAQ start from real questions, for example from issues tagged `kind/docs`? ## Related #5 (CI and releases), README.md, CONTEXT.md, `docs/milestones`, `docs/adr`, the blog repo `twisla/blog`.

twisla added the

area/website labels 2026-10-05 09:57:21 +00:00

twisla referenced this issue

2026-10-05 09:59:35 +00:00

Apps from the SD card: Lua Apps with an API to our services and widgets #13

twisla referenced this issue