Integracja z dokumentacją i styleguide’em

Bez dokumentacji każdy programista na nowo ustala konwencje: kolejność nagłówków, dostępne nazwy klas oraz sytuacje, w których należy użyć modala zamiast drawera. Udokumentowany styleguide ułatwia znalezienie właściwej odpowiedzi i na dużą skalę eliminuje zgadywanie.

Narzędzia takie jak Storybook, Histoire (Vue) i Ladle renderują komponenty w izolacji wraz z dokumentacją — przykład jest zawsze zsynchronizowany z rzeczywistym kodem. Statyczne pliki dokumentacji (w wiki lub repozytorium) nieuchronnie się dezaktualizują, a żywa dokumentacja nie ma tego problemu.

Dla każdego komponentu należy pokazać minimalny HTML potrzebny do jego użycia: <app-button variant="primary">Save</app-button>. Należy pokazać warianty (primary, secondary, danger), stany (loading, disabled) i przypadki brzegowe (długi tekst, ikona, pełna szerokość). Zespoły faktycznie korzystają z przykładów, które można dokładnie skopiować i wkleić do prawdziwej strony.

Najlepsza dokumentacja wyświetla przykład obok kodu źródłowego. Storybook robi to natywnie, a mdx-deck, Docusaurus i Astro Starlight obsługują MDX z renderowanym na żywo JSX. Widok rzeczywistego rezultatu podczas czytania znaczników natychmiast usuwa wątpliwość: „czy to działa?”

Należy opisać zachowanie związane z dostępnością, które jest wbudowane w każdy komponent: obsługiwane interakcje klawiaturowe, role ARIA i sposób zarządzania fokusem. Konsumenci korzystający z komponentu otrzymują kompletną obsługę dostępności, a osoby przeglądające kod mogą sprawdzić, czy nie naruszają kontraktu.

Należy pokazywać wyraźne antywzorce: „Nie należy używać komponentu Modal do ważnych, tymczasowych komunikatów — zamiast tego należy użyć Toast”. Negatywny przykład często lepiej zapada w pamięć niż pozytywny. Do każdego zalecenia należy dodać jasne przeciwwskazanie, aby uwidocznić możliwe tryby niepowodzenia.

Należy udokumentować wzorce nazewnictwa: BEM, atomic CSS, CSS Modules i kompozycję narzędzi Tailwind. Trzeba precyzyjnie określić zasady dotyczące nazw klas, nazw właściwości niestandardowych i ścieżek plików. Spójne nazewnictwo zmniejsza obciążenie poznawcze, a niespójne odbiera czas każdemu programiście — bez końca.

Należy zapisywać nie tylko podjęte decyzje, lecz także ich uzasadnienie. Stwierdzenie „Wybraliśmy React zamiast Vue, ponieważ…” zachowuje kontekst dla przyszłych współtwórców. ADR-y (Architecture Decision Records) w formacie Markdown, umieszczone obok kodu, to lekki format, który przetrwa zmiany w zespole.

Nowy członek zespołu powinien móc dostarczyć swój pierwszy komponent w ciągu jednego dnia. Lista kontrolna może obejmować: skonfigurowanie repozytorium, zainstalowanie zależności, uruchomienie Storybooka, znalezienie właściwego szablonu komponentu, napisanie dokumentacji i otwarcie PR-a. Warto śledzić czas do pierwszego PR-a jako wskaźnik — im krótszy, tym lepiej.

Najlepszą dokumentację łatwo znaleźć zarówno nowym osobom, jak i doświadczonym użytkownikom. Należy korzystać z witryny dokumentacji z wyszukiwarką (Algolia dla Docusaurus, wbudowane wyszukiwanie w Starlight). Komponenty warto oznaczać wieloma aliasami — wyszukiwanie „Modal” powinno znajdować komponent także po hasłach Dialog, Popup i Overlay.

Dokumentację warto połączyć z testami regresji wizualnej: Chromatic wykonuje migawki każdej historii Storybooka przy każdym PR-ze i pokazuje różnice wizualne. Scalony PR, który przypadkowo zmienia styl przycisku Button w całej dokumentacji, sam zablokuje możliwość scalenia. W ten sposób dokumentacja zostaje połączona z aktywnym testowaniem systemu projektowego.

Należy udokumentować rzeczy znane wyłącznie opiekunowi: pułapki, niedokończone abstrakcje i obejścia czekające na uporządkowanie. Przyszły opiekun — także osoba, która przejmie tę rolę — podziękuje za zapisanie tej wiedzy instytucjonalnej, zanim zostanie zapomniana.

Dlaczego preferuje się żywą dokumentację (renderowaną obok kodu) zamiast statycznych plików dokumentacji?

Dokumentacja zwielokrotnia wartość systemu projektowego. Należy używać żywej dokumentacji (Storybook, Histoire, Ladle), która importuje rzeczywisty kod komponentów. Trzeba pokazywać minimalne, działające przykłady, dokumentować dostępność, zapisywać decyzje, tworzyć pary zaleceń i przeciwwskazań oraz łączyć dokumentację z testami regresji wizualnej. Dokumentację należy traktować jako pełnoprawny rezultat, a nie dodatek.