Docs in the self-documenting world

Abstract

Most of the teams are still in a never-ending quest for the documentation sweet spot. The place that you don’t have spend too much time maintaining it, yet it brings a lot of value and is up to date.

For some the starting point was from agile manifesto or software craftsmanship misunderstanding, which is not-documenting at all. Others decided to build a comprehensive documentation, soon to discover it is a challenge to keep it up with the reality (which is the code).

There is a better way to build a good Developer Experience. I will share several options, that you may take advantage of, including:

  • partially executable documentation without (non-docstring)
  • human- and machine-readable HTTP API documentation
  • automated tests as documentation

[PL] 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

Target audience

The perfect audience

  • writes code long-term (that will be used for at least 6+ months)
  • creates automated tests (or code snippets to verify that the code works)

The presented patterns shall bring value to developers regardless of the domain.

Attendees should learn of how to reuse code between tests and documentation. This will improve their documentation and keep it always up to date.