Documentation: a fuller wiki for the people who use, run and extend Postulo, readable in more than English

tiagoagueda commented

2026-10-01 09:46:28 +00:00

Owner

Requested by the maintainer on 2026-10-01.

The wiki is the project's documentation: 23 pages and about 77,000 words in postulo.wiki, all in English, plus four files under docs/ in the repository (PLAN.md, PLUGINS.md, THREAT-MODEL.md, TRANSLATING.md). The interface is offered in dozens of languages; everything that explains it is offered in one. And the pages grew issue by issue, so what is covered depends on what happened to be built with a wiki commit rather than on what a reader needs to find.

1.0.0 is "the first release that claims to be finished". This issue is the documentation's share of that claim: better and more comprehensive documentation, preferably, but not only, in several languages.

1. More comprehensive

Start from the reader, not from the page list. Three readers, each with a path from first contact to done:

Somebody using an instance: a first hour (sign in, capture a posting, apply, be reminded), then one page per thing they can do, each naming the page of the interface it describes. Whatever the interface offers and no page explains is a gap; so is every setting under Settings with no sentence anywhere.
Somebody running one: install, configure, upgrade, back up, restore, harden, observe, troubleshoot. Every setting the code reads appears in Configuration with its default and what it costs to change; every management command is named with its options.
Somebody extending it: the plugin surface, the HTTP API, the browser extensions and the official plugins, each with a worked example that runs.

Work to do:

An inventory first: every page of the interface, every setting, every command, every API call, every official plugin, against the page that documents it (or none). tests/test_wiki_surface.py already does this for API calls, metrics, postulo.plugins.api names and entry-point groups; extend the same idea to settings (POSTULO_*), management commands and named URL patterns, so that a gap fails a test instead of waiting to be noticed.
Fill the gaps the inventory finds, one page (or one section) per commit, as the wiki is written today.
A glossary: listing, application, capture, connection, store, source, notifier, errand. The words are used consistently in the interface and are explained nowhere in one place.
Screenshots that are regenerated rather than hand-taken, so they do not go stale with every interface change (the browser suite already drives every page).
Corrections to what is there: the read-only review of 2026-09-29 found statements in the wiki and in CONTRIBUTING.md that the code contradicts. Those are filed as their own issues and are not repeated here.

2. In more than one language

Preferred, not a condition for closing section 1.

Decide where translated pages live. Forgejo's wiki has no notion of a page's language. The options are a suffix per page (Getting-started.fr.md), a folder per language, or publishing the documentation as a site built from the wiki repository with a language switcher. The decision should say how a reader lands on their language and what they see when a page has no translation yet (the English page, said to be English).
Decide how they are kept current. A translated page that silently describes last year's interface is worse than an English one. Each translation needs to record which revision of the source it was made from, and something (a script, a check) has to list the pages whose source moved since.
Use the same rules as the catalogues. docs/TRANSLATING.md already says how a translation is made, flagged draft until a speaker has read it, and reviewed. Documentation should follow it rather than invent a second process; Weblate can carry Markdown if the pages are to be translated there.
Start small. French and Portuguese (pt-PT, with pt-BR drafted from it), the languages the interface is worked in every day, for the user-facing path of section 1 first. Operators' and developers' pages can stay English longer.
In-app help is already translated. #302 decided that the help drawer's text is written as templates and translated through the catalogues, with the wiki pointing at the same text. Whatever is decided here should not create a second copy of that text to translate.

Done when

The inventory exists as a test, and it passes: no interface page, setting, command, API call or official plugin without its place in the documentation.
Each of the three readers can follow their path from the wiki's Home without leaving it.
The decision on where translations live and how they are kept current is written into docs/TRANSLATING.md.
The user-facing path is available in at least French and Portuguese, each page marked reviewed or draft, and a reader on an untranslated page is told so.

Requested by the maintainer on 2026-10-01. The wiki is the project's documentation: 23 pages and about 77,000 words in `postulo.wiki`, all in English, plus four files under `docs/` in the repository (`PLAN.md`, `PLUGINS.md`, `THREAT-MODEL.md`, `TRANSLATING.md`). The interface is offered in dozens of languages; everything that explains it is offered in one. And the pages grew issue by issue, so what is covered depends on what happened to be built with a wiki commit rather than on what a reader needs to find. 1.0.0 is "the first release that claims to be finished". This issue is the documentation's share of that claim: **better and more comprehensive documentation, preferably, but not only, in several languages.** ## 1. More comprehensive Start from the reader, not from the page list. Three readers, each with a path from first contact to done: - **Somebody using an instance:** a first hour (sign in, capture a posting, apply, be reminded), then one page per thing they can do, each naming the page of the interface it describes. Whatever the interface offers and no page explains is a gap; so is every setting under *Settings* with no sentence anywhere. - **Somebody running one:** install, configure, upgrade, back up, restore, harden, observe, troubleshoot. Every setting the code reads appears in *Configuration* with its default and what it costs to change; every management command is named with its options. - **Somebody extending it:** the plugin surface, the HTTP API, the browser extensions and the official plugins, each with a worked example that runs. Work to do: - An inventory first: every page of the interface, every setting, every command, every API call, every official plugin, against the page that documents it (or none). `tests/test_wiki_surface.py` already does this for API calls, metrics, `postulo.plugins.api` names and entry-point groups; extend the same idea to settings (`POSTULO_*`), management commands and named URL patterns, so that a gap fails a test instead of waiting to be noticed. - Fill the gaps the inventory finds, one page (or one section) per commit, as the wiki is written today. - A glossary: listing, application, capture, connection, store, source, notifier, errand. The words are used consistently in the interface and are explained nowhere in one place. - Screenshots that are regenerated rather than hand-taken, so they do not go stale with every interface change (the browser suite already drives every page). - Corrections to what is there: the read-only review of 2026-09-29 found statements in the wiki and in `CONTRIBUTING.md` that the code contradicts. Those are filed as their own issues and are not repeated here. ## 2. In more than one language Preferred, not a condition for closing section 1. - **Decide where translated pages live.** Forgejo's wiki has no notion of a page's language. The options are a suffix per page (`Getting-started.fr.md`), a folder per language, or publishing the documentation as a site built from the wiki repository with a language switcher. The decision should say how a reader lands on their language and what they see when a page has no translation yet (the English page, said to be English). - **Decide how they are kept current.** A translated page that silently describes last year's interface is worse than an English one. Each translation needs to record which revision of the source it was made from, and something (a script, a check) has to list the pages whose source moved since. - **Use the same rules as the catalogues.** `docs/TRANSLATING.md` already says how a translation is made, flagged `draft` until a speaker has read it, and reviewed. Documentation should follow it rather than invent a second process; Weblate can carry Markdown if the pages are to be translated there. - **Start small.** French and Portuguese (pt-PT, with pt-BR drafted from it), the languages the interface is worked in every day, for the user-facing path of section 1 first. Operators' and developers' pages can stay English longer. - **In-app help is already translated.** #302 decided that the help drawer's text is written as templates and translated through the catalogues, with the wiki pointing at the same text. Whatever is decided here should not create a second copy of that text to translate. ## Done when - The inventory exists as a test, and it passes: no interface page, setting, command, API call or official plugin without its place in the documentation. - Each of the three readers can follow their path from the wiki's *Home* without leaving it. - The decision on where translations live and how they are kept current is written into `docs/TRANSLATING.md`. - The user-facing path is available in at least French and Portuguese, each page marked reviewed or draft, and a reader on an untranslated page is told so.

tiagoagueda added this to the 1.0.0 milestone

2026-10-01 09:46:28 +00:00

tiagoagueda added the

labels

2026-10-01 09:46:28 +00:00

tiagoagueda referenced this issue

2026-10-01 10:34:02 +00:00

Wiki in several languages: find out whether it can be done, and how, before any page is translated #352

tiagoagueda referenced this issue

2026-10-01 10:34:03 +00:00

Documentation: screenshots and renderings of a demo instance, in the wiki and the READMEs, generated rather than taken by hand #353

tiagoagueda commented

2026-10-01 10:34:04 +00:00

Author

Owner

Two parts of this issue were asked for on their own on 2026-10-01 and are tracked separately:

#352: assess whether, and how, the wiki can be in several languages (the question this issue's second section leaves open).
#353: screenshots and renderings of a demo instance, generated rather than taken by hand (the screenshots point of the first section).

Two parts of this issue were asked for on their own on 2026-10-01 and are tracked separately: - #352: assess whether, and how, the wiki can be in several languages (the question this issue's second section leaves open). - #353: screenshots and renderings of a demo instance, generated rather than taken by hand (the screenshots point of the first section).

tiagoagueda referenced this issue

2026-10-03 01:59:13 +00:00

Docker Compose at home: one deployment page for a homelab, and the drift between the compose files and the wiki #704

tiagoagueda commented

2026-10-03 01:59:27 +00:00

Author

Owner

The maintainer's list of 2026-10-02 says that, since Postulo is mostly a homelab project, the deployment documentation using Docker Compose should be improved. #704 is the issue for it.

It relates to this one as a slice of the operator path in section 1 (“Somebody running one: install, configure, upgrade, back up …”). It covers Compose only: one deployment page, a stand-alone example, reverse-proxy recipes and storage notes, and it corrects where the wiki and the compose files disagree today. It does not touch the rest of this issue (the inventory test, the glossary, the other two readers, translation), which stays here, and it should not wait for it.

From the list of improvements of 2026-10-02.

The maintainer's list of 2026-10-02 says that, since Postulo is mostly a homelab project, the deployment documentation using Docker Compose should be improved. #704 is the issue for it. It relates to this one as a slice of the operator path in section 1 (“Somebody running one: install, configure, upgrade, back up …”). It covers Compose only: one deployment page, a stand-alone example, reverse-proxy recipes and storage notes, and it corrects where the wiki and the compose files disagree today. It does not touch the rest of this issue (the inventory test, the glossary, the other two readers, translation), which stays here, and it should not wait for it. From the list of improvements of 2026-10-02.

tiagoagueda referenced this issue

2026-11-01 14:58:46 +00:00

Wiki in several languages: every page through Weblate, published at wiki.tiagoagueda.com #1215

tiagoagueda commented

2026-11-11 15:03:22 +00:00

Author

Owner

The question in section 2, "decide where translated pages live" and "how they are kept current", is answered. #352 asked it, and the maintainer chose on 2026-11-01; #1215 carries the work:

Where: a documentation site built from the wiki repository, at https://wiki.tiagoagueda.com. English is the source and stays at /; every other language is under /<tag>/ with its own menu and search. A page with no translation is shown in English and says so in the reader's language.
How they are translated and kept current: in Weblate, one component per page in the Markdown format, by paragraph, with the same draft rule as the catalogues. A changed English paragraph makes its translations need review.
Which languages: fr-FR and pt-PT are reviewed and a release waits for them, on the pages of the stages already open. Ten more are scaffolded and no release waits for them.

So of this section's bullets, the first three are decided and the fourth ("start small") is under way in #1215. What remains here is section 1 and this issue's own "Done when".

🤖 Generated with Claude Code

The question in section 2, "decide where translated pages live" and "how they are kept current", is answered. #352 asked it, and the maintainer chose on 2026-11-01; #1215 carries the work: - **Where:** a documentation site built from the wiki repository, at https://wiki.tiagoagueda.com. English is the source and stays at `/`; every other language is under `/<tag>/` with its own menu and search. A page with no translation is shown in English and says so in the reader's language. - **How they are translated and kept current:** in Weblate, one component per page in the Markdown format, by paragraph, with the same draft rule as the catalogues. A changed English paragraph makes its translations need review. - **Which languages:** fr-FR and pt-PT are reviewed and a release waits for them, on the pages of the stages already open. Ten more are scaffolded and no release waits for them. So of this section's bullets, the first three are decided and the fourth ("start small") is under way in #1215. What remains here is section 1 and this issue's own "Done when". 🤖 Generated with [Claude Code](https://claude.com/claude-code)

tiagoagueda referenced this issue

2026-11-11 15:03:22 +00:00

Wiki in several languages: find out whether it can be done, and how, before any page is translated #352

Rows
Columns

Documentation: a fuller wiki for the people who use, run and extend Postulo, readable in more than English #345

1. More comprehensive

2. In more than one language

Done when