Walkthrough kodu czy nagranie ekranu? Pokaż decyzję, nie pulpit
Opublikowano · Zaktualizowano · Jakub Kuźnicki
Notatka o przepływie first-party: porównanie korzysta z kontrolek Scribe i deterministycznego przykładu; poniżej znajduje się sprawdzony eksport tego fixture.
Zasady aktualizacji: fakty o produkcie, cytowane źródła i sprawdzone dowody wyniku są ponownie weryfikowane, gdy się zmienią.
Krótka odpowiedź: nagraj decyzję, którą widz ma zapamiętać
Nagranie ekranu pokazuje cały pulpit: zakładki, ruch kursora, interfejs edytora i moment, w którym autor znajduje właściwą linię. Walkthrough kodu może pokazać mniejszą rzecz, której potrzebuje odbiorca: która gałąź się wykona, co zwróci i dlaczego pojawia się następne wywołanie. Żaden format nie jest zawsze lepszy. Wybór zależy od tego, czy widz potrzebuje środowiska, czy rozumowania. Ten tekst sprawdza ten sam mały przykład w obu modelach i konfrontuje przepływ z kontrolkami Scribe. Dowód wyjściowy jest jawny: poniższy klip to rzeczywisty eksport tego przykładu do MP4 ze sprawdzonym plakatem; nie jest benchmarkiem. Własny kod możesz wkleić do Scribe.
Wejście: jedna gałąź i jedno miejsce wywołania
function choosePath(path?: string) {
if (!path) return "/";
return path.startsWith("/") ? path : `/${path}`;
}
choosePath("docs");Przepływ kontroli był prosty: wklejenie, profil TypeScript, podgląd i odtworzenie. To samo wejście jest kotwicą porównania; klip poniżej jest rzeczywistym eksportem tego fixture, a nie ilustracją stockową.
Co zachowuje nagranie ekranu
- Edytor, terminal lub przeglądarkę, gdy środowisko jest częścią lekcji.
- Ruch kursora, gdy ważne jest odtworzenie widocznej czynności.
- Niedoskonałe momenty pracy, jeśli widz ma powtórzyć operację krok po kroku.
Kontekst bywa potrzebny, ale zmusza widza do filtrowania. Nagranie może sprawić, że trzy linie decyzji zamienią się w wycieczkę po komputerze autora. Jeśli pulpit nie jest lekcją, usuń go już na etapie scenariusza.
Co walkthrough czyni czytelnym
Walkthrough pozwala podzielić wyjaśnienie w miejscu decyzji: pusta ścieżka staje się katalogiem głównym, ścieżka bez ukośnika dostaje ukośnik, a miejsce wywołania przekazuje konkretną wartość. Odtwarzanie linia po linii w Scribe pomaga pokazać wybraną kolejność zamiast wędrówki kursora po pulpicie. Sekcja dla deweloperów na stronie funkcji opisuje produkt, ale ten przykład nie udaje benchmarku.
Przed eksportem usuń obce linie, zadbaj o czytelność i wybierz kadr zgodny z miejscem publikacji. Cennik opisuje eksport; podgląd jest pierwszym, tańszym testem tego, czy wyjaśnienie w ogóle działa.
Praktyczna reguła wyboru
- Wybierz nagranie ekranu, gdy środowisko jest dowodem: konfiguracją, reprodukcją albo widoczną interakcją.
- Wybierz walkthrough, gdy widz ma zapamiętać gałąź, kolejność lub zależność.
- Połącz formaty tylko wtedy, gdy drugi dodaje kontekst, a nie powtarza pierwszego.
Uczciwy test nie pyta, co wygląda bardziej efektownie. Zapytaj, co odbiorca ma umieć wyjaśnić dziesięć minut później. Jeśli odpowiedzią jest „gdzie kliknąć”, zostaw pulpit. Jeśli „dlaczego działa ta gałąź”, pokaż rozumowanie.
Dowód i granica tej notatki
Manifest first-party zawiera wejście, przepływ, sprawdzony plik i obserwacje ze źródeł. To jeden kontrolowany przykład, bez twierdzenia o wyniku dla każdego repozytorium, przeglądarki lub odbiorcy. Przeczytaj Wyjaśnij kod w 60 sekund, jeśli chcesz zobaczyć dłuższy przykład z faktycznie sprawdzonym klipem.