docs: narzedzie na stronach, na ktore ludzie juz trafiaja - #219
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
535 5.7.139Strony 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.139już 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.npxidzie 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.