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

New issue

Closed

opened 2026-10-01 10:34:03 +00:00 by tiagoagueda · 1 comment

tiagoagueda commented

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

Owner

Requested by the maintainer on 2026-10-01: improve the wiki and the other documentation with screenshots and renderings of a demo Postulo instance. Part of #345, asked on its own.

What is there today

The wiki has 23 pages and three images: the logo and two donation images. Not one picture of the interface. A page explains the board, the calendar, a CV's preview or Server settings in words only.
README.md shows the logo and nothing of the product. The plugin and extension READMEs show nothing either.
Everything needed to make pictures already exists: manage.py seed_demo <email> --seed 2026 fills an account with a fictional but believable job search, deterministically; the browser suite drives every page with Playwright (tests/e2e/), at phone and desktop widths and in both themes; the document themes render CVs and letters to PDF.

What to build

A demo instance made on demand, not kept: a throwaway database seeded by seed_demo, so every picture shows the same fictional person, the same companies and the same dates, and nobody's real data can appear in the documentation.
One command that takes every picture: it starts that instance, visits a named list of pages and states (the dashboard, the board, an application's timeline, the capture review, a CV's preview, the calendar, Settings, Server settings and so on), and writes each to a stable file name under the wiki's images/ (and wherever the READMEs keep theirs). Stable names mean a page's Markdown does not change when a picture is retaken.
Renderings as well as screenshots: a CV and a letter in each built-in theme, as pictures of the PDF, for the pages on CVs, letters and Design, and for postulo-templates when it carries templates of its own.
The pictures are retaken, not kept up by hand. The interface changes every week (0.5.0 alone moves the search, the filters, the board and the forms). A picture that no longer matches is worse than none, so the command runs before a release (a step in CONTRIBUTING.md § Making a release), and a check says which pictures changed.
Placed in the pages: each user-facing wiki page gets the pictures its text describes, each with alternative text that says what the picture shows (the wiki's reader may not see it), and the README gets a few that show what Postulo is at a glance.

Decisions to take while building

Which widths and themes. One desktop picture per page in the light theme is the minimum; phone pictures where the page is about the phone (#73); the dark theme only where it is the subject.
Languages. Pictures show interface text. If the wiki is translated (the companion issue assesses whether), generated pictures are what makes a picture per language affordable: the same command, run with another language.
What must not be in a picture. The demo data is fictional by design; check that it stays so (no real company names or logos, which are other people's marks: TRADEMARKS.md), and that nothing from the machine taking the pictures leaks in (a real address, a real instance name).
Size. PNG files in a git repository add up. Fix a width, compress, and consider keeping only the current set rather than every past one.
A public demo instance is a different thing (something to host, reset and secure) and is not asked for here; say so in the README if people ask for one.

Done when

One documented command regenerates every picture from a seeded throwaway instance, and running it twice on an unchanged tree changes nothing.
Every user-facing wiki page shows the interface it describes, with alternative text; README.md shows the product.
The release handbook has the step, and a stale picture is something a check reports rather than something a reader notices.

Requested by the maintainer on 2026-10-01: **improve the wiki and the other documentation with screenshots and renderings of a demo Postulo instance.** Part of #345, asked on its own. ## What is there today - The wiki has 23 pages and three images: the logo and two donation images. **Not one picture of the interface.** A page explains the board, the calendar, a CV's preview or *Server settings* in words only. - `README.md` shows the logo and nothing of the product. The plugin and extension READMEs show nothing either. - Everything needed to make pictures already exists: `manage.py seed_demo <email> --seed 2026` fills an account with a fictional but believable job search, deterministically; the browser suite drives every page with Playwright (`tests/e2e/`), at phone and desktop widths and in both themes; the document themes render CVs and letters to PDF. ## What to build - **A demo instance made on demand**, not kept: a throwaway database seeded by `seed_demo`, so every picture shows the same fictional person, the same companies and the same dates, and nobody's real data can appear in the documentation. - **One command that takes every picture**: it starts that instance, visits a named list of pages and states (the dashboard, the board, an application's timeline, the capture review, a CV's preview, the calendar, *Settings*, *Server settings* and so on), and writes each to a stable file name under the wiki's `images/` (and wherever the READMEs keep theirs). Stable names mean a page's Markdown does not change when a picture is retaken. - **Renderings as well as screenshots**: a CV and a letter in each built-in theme, as pictures of the PDF, for the pages on CVs, letters and *Design*, and for postulo-templates when it carries templates of its own. - **The pictures are retaken, not kept up by hand.** The interface changes every week (0.5.0 alone moves the search, the filters, the board and the forms). A picture that no longer matches is worse than none, so the command runs before a release (a step in `CONTRIBUTING.md` § *Making a release*), and a check says which pictures changed. - **Placed in the pages**: each user-facing wiki page gets the pictures its text describes, each with alternative text that says what the picture shows (the wiki's reader may not see it), and the README gets a few that show what Postulo is at a glance. ## Decisions to take while building - **Which widths and themes.** One desktop picture per page in the light theme is the minimum; phone pictures where the page is about the phone (#73); the dark theme only where it is the subject. - **Languages.** Pictures show interface text. If the wiki is translated (the companion issue assesses whether), generated pictures are what makes a picture per language affordable: the same command, run with another language. - **What must not be in a picture.** The demo data is fictional by design; check that it stays so (no real company names or logos, which are other people's marks: `TRADEMARKS.md`), and that nothing from the machine taking the pictures leaks in (a real address, a real instance name). - **Size.** PNG files in a git repository add up. Fix a width, compress, and consider keeping only the current set rather than every past one. - **A public demo instance** is a different thing (something to host, reset and secure) and is not asked for here; say so in the README if people ask for one. ## Done when - One documented command regenerates every picture from a seeded throwaway instance, and running it twice on an unchanged tree changes nothing. - Every user-facing wiki page shows the interface it describes, with alternative text; `README.md` shows the product. - The release handbook has the step, and a stale picture is something a check reports rather than something a reader notices.

tiagoagueda added this to the 0.6.0 milestone

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

tiagoagueda added the

documentation

enhancement

labels

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

tiagoagueda referenced this issue

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

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

tiagoagueda referenced this issue from a commit

2026-10-06 04:51:05 +00:00