Dokumentacja to funkcja

Dokumentacja nie jest oddzielona od Twojego produktu. Jest jego częścią.

Wielu programistów stosuje wadliwy schemat:

  • Zbuduj funkcję.
  • Przetestuj funkcję.
  • Wdróż funkcję.
  • Udokumentuj funkcję.

Użytkownicy nie doświadczają Twojego kodu. Doświadczają Twojego interfejsu, Twoich procesów pracy i Twojej dokumentacji. Dla użytkownika dokumentacja to funkcja.

Twórcy zaniedbują dokumentację, ponieważ już rozumieją produkt. Wiesz, dlaczego podjąłeś określone decyzje. Wiesz, jak działa API. Znasz skróty.

Użytkownik nie wie. To, co dla Ciebie jest oczywiste, dla nich jest zagadką.

Traktuj powtarzające się pytania jako dług dokumentacyjny. Jeśli ludzie zadają to samo pytanie dwa razy, masz problem. Albo Twój produkt jest niejasny, albo Twoja dokumentacja jest niekompletna. Czasami musisz naprawić API. Często musisz naprawić dokumentację.

Dobra dokumentacja zmniejsza tarcie. Szybko odpowiada na te pytania:

  • Co to jest?
  • Dlaczego powinienem tego używać?
  • Jak zacząć?
  • Jaka jest najlepsza metoda?
  • Jak wygląda prosty przykład?

Celem nie jest kompletność. Celem jest dynamika.

Świetna dokumentacja uczy wzorców i intencji. Wyjaśnia, dlaczego framework działa w określony sposób. Dzięki temu użytkownicy stają się bardziej efektywni.

Dokumentacja wpływa na Twój biznes w sposób dyskretny:

  • Wskaźniki adopcji.
  • Szybkość onboardingu.
  • Koszty wsparcia.
  • Wzrost społeczności.
  • Doświadczenie programisty (Developer Experience).

Wpływu dobrej dokumentacji nie widać łatwo. Brak dobrej dokumentacji zauważasz natychmiast.

Pamiętaj, że dokumentacja jest także dla Ciebie. Zachowuje Twoją wiedzę dla Twoich przyszłych wersji. Rejestruje decyzje, abyś nie musiał ponownie szukać odpowiedzi miesiące później.

Jakość produktu i jakość dokumentacji są ze sobą powiązane.

  • Niejasne oprogramowanie wymaga więcej dokumentacji.
  • Przejrzyste oprogramowanie wymaga mniej.
  • Dobra dokumentacja obnaża zły projekt.

Przestań traktować dokumentację jako dodatek robiony na końcu. Używaj jej, aby wymusić klarowność. Klarowność poprawia Twój projekt. Poprawiony projekt poprawia Twój produkt.

Źródło: https://dev.to/stinklewinks/documentation-is-a-feature-228n