Tytuł oraz abstrakt

Dokumentacja w samodokumentującym się świecie

Większość zespołów, z którymi pracowałem kroczyła nigdy niekończącą się ścieżką w poszukiwaniu złotego środka w pisaniu dokumentacji. Miejscu, w którym czerpie się korzyści z posiadania pomocnej dokumentacji, jednak nie spędza się zbyt wiele czasu i energii na jej tworzeniu.

Dla niektórych punktem wyjściowym jest popularny błąd, w którym mówi się, że kodu nie należy dokumentować, gdyż kod powinien być sam w sobie wystarczająco czytelny. Inni z kolei tworzą bardzo dokładną dokumentację i szybko wpadają w pułapkę ogromnego kosztu jej utrzymywania.

Jest lepsza droga, aby inni programiści mieli dobre wrażenia. Podzielę się kilkoma sposobami, jak na przykład:

  • Częściowo lub całkowicie wykonywalna dokumentacja
  • Dokumentacja API zrozumiała dla maszyn i ludzi
  • Testy automatyczne jako dokumentacja