Sitelet https://github.com/msgwing/ZeroSMTP/pull/219
Skip to content

docs: narzedzie na stronach, na ktore ludzie juz trafiaja - #219

Merged
msgwing merged 1 commit into
mainfrom
tool-where-people-land
Aug 22, 2026
Merged

msgwing merged 1 commit into
mainfrom
tool-where-people-land

Conversation

@msgwing

@msgwing msgwing commented Aug 22, 2026

Copy link
Copy Markdown
Owner

Zmierzone przed napisaniem czegokolwiek: zero z sześciu stron błędów wspominało zerosmtp-check, README główne — zero, jedna z dziewiętnastu stron dokumentacji. A narzędzie odpowiada dokładnie na pytanie, o którym te strony są.

Czyli: ktoś szuka komunikatu błędu, trafia na stronę napisaną pod ten komunikat, czyta kilkaset słów i nigdy się nie dowiaduje, że jest jednolinijkowiec, który powiedziałby mu to w dwie sekundy. To nie jest luka marketingowa. To strona opisująca problem i zatajająca rzecz, która go rozwiązuje.

Powierzchnia Przed Po
strony błędów 0/6 6/6
README 0 1 — w cytacie o 535 5.7.139
strony docs 1/19 4/19

Strony błędów są generowane, więc blok wszedł do generatora — dostało go sześć naraz i dostanie każda dodana później. O to chodzi w poprawianiu tego u źródła.

README: cytat o 535 5.7.139 już siedział w momencie najwyższej intencji na najczęściej oglądanej stronie — 46 z 55 unikalnych odwiedzających ląduje w korzeniu repo — i wskazywał stronę dokumentacji. Teraz podaje też komendę.

TROUBLESHOOTING.md to homepage paczki npm, i dokładnie w miejscu, gdzie mówi „uruchom sprawdzenie łączności", podawał ./check-connection.sh — czyli wymagał najpierw sklonowania repozytorium. To było poprawne, gdy paczka zwracała 404. Nie jest od piątku. npx idzie pierwszy, skrypt zostaje dla maszyn bez Node — a to realny przypadek na zamkniętym Windowsie.

PRINTERS.md dostaje ścieżkę 1102, bo kod z panelu jest najtrudniejszą wersją tego problemu: wygląda jak awaria sprzętu i nie mówi nic o serwerze pocztowym. Odpowiedź, której serwisant potrzebuje na wizycie, brzmi „urządzenia nie trzeba wymieniać" — i teraz strona to mówi.

Nie dodane do pozostałych piętnastu stron. Powtarzanie tego wszędzie to wypełniacz, a czytelnik, który widzi ten sam blok na każdej stronie, przestaje czytać wszystkie.

Measured before writing anything: zero of the six error pages mentioned
zerosmtp-check, the main README mentioned it zero times, and one of nineteen
docs pages did. The tool answers the exact question those pages are about.

So somebody searches an error string, lands on the page written for that
string, reads several hundred words, and never learns there is a one-line
command that would have told them in two seconds. That is not a marketing gap.
It is a page describing a problem while withholding the thing that solves it.

The error pages are generated, so the block goes in the generator and all six
got it at once - along with every one added later, which is the point of
fixing it there rather than in the pages.

README: the blockquote about 535 5.7.139 already sat at the highest-intent
moment on the highest-traffic page - 46 of 55 unique visitors land on the
repository root - and pointed at a docs page. It now also gives the command.

TROUBLESHOOTING.md is the npm package's own homepage, and at the exact point
where it says "run the connectivity-only check" it offered ./check-connection.sh
- which requires cloning the repository first. That wording was correct when
the package returned 404. It has not been since Friday. npx goes first now and
the shell script stays for machines with no Node, which is a real case on a
locked-down Windows box.

PRINTERS.md gets the 1102 path, because a panel code is the hardest version of
this to act on: it looks like hardware failing and says nothing about a mail
server. The answer a technician needs on a service call is that the device does
not need replacing, and now the page says it.

Not added to the other fifteen docs pages. Repeating it everywhere would be
padding, and a reader who sees the same block on every page stops reading all
of them.
@msgwing
msgwing enabled auto-merge August 22, 2026 17:42
@github-actions github-actions Bot added the docs label Aug 22, 2026
@msgwing
msgwing merged commit c9a4bf9 into main Aug 22, 2026
36 checks passed
@msgwing
msgwing deleted the tool-where-people-land branch August 22, 2026 17:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant