Dokumentacja jako kod

Jestem naprawdę przekonany, że dokumentacja jest częścią aplikacji . Powinna być rozwijana, aktualizowana i sprawdzana przy użyciu tych samych procesów i narzędzi, co kod aplikacji.

Jeśli dokumentacja jest przechowywana gdzie indziej, np. na oddzielnej wiki , to w zasadzie przestaje być aktualna w ciągu 5 minut od opublikowania .

Oznacza to, że dokumentacja powinna znajdować się w repozytorium git. Jeśli jakieś zachowanie systemu zostanie zmienione podczas naprawiania błędów lub opracowywania nowej funkcji, odpowiednia dokumentacja powinna zostać zaktualizowana w tym samym PR. Takie podejście pomaga utrzymać dokumentację na bieżąco .

To naprawdę proste, jeśli używasz monorepo . Wszystkie dokumenty i kod są umieszczone w jednym miejscu, więc łatwo znaleźć to, czego potrzebujesz. Rzeczy stają się bardziej skomplikowane, jeśli masz wiele mikrorepo . Nawet jeśli dokumenty są aktualne, użytkownikom trudno je znaleźć. Zwykle rozwiązuje się to, publikując dokumenty w centralnym portalu jako część procesu CI lub obecnie, korzystając z bota AI, który pomaga.

Niedawno Pinterest opublikował artykuł o tym, jak przyjęli podejście dokumentowania jako kodu . Ponieważ używają mikrorepozytoriów, głównym wyzwaniem było uczynienie dokumentacji możliwą do odnalezienia dla ich użytkowników w setkach repozytoriów.

Co zrobili:
🔸 Przeniesiono ich dokumenty do repozytoriów git, korzystając z języka znaczników Markdown.
🔸 Wykorzystano MkDocs w CI do wygenerowania wersji HTML dokumentów.
🔸 Utworzono centralne miejsce do przechowywania i indeksowania dokumentów o nazwie PDocs (Pinterest Docs).
🔸 Zintegrowana dokumentacja z GenAI — botem AI połączonym z głównymi kanałami komunikacji firmy.
🔸 Zbudowałem narzędzie umożliwiające migrację starych stron wiki do gita za pomocą jednego kliknięcia.

Nie znam żadnego standardowego rozwiązania dla agregacji dokumentów w wielu repozytoriach, więc byłoby wspaniale, gdyby Pinterest w przyszłości udostępnił swoje PDocs jako open-source. Myślę, że mogłoby to naprawdę pomóc wielu zespołom w ulepszeniu procesów dokumentowania.

#engineering #documentation
👇🏻👇🏻👇🏻👇🏻👇🏻

Documentation As a Code

I have a really strong opinion that the documentation is part of the application. It should be developed, updated and reviewed using the same processes and tools as the application code.

If the documentation is stored somewhere else, like in a separate wiki, it's basically dead within 5 minutes after it's published.

This means documentation should live in the git repo. If some system behavior is changed during bugfixing or a new feature development, the relevant documentation should be updated in the same PR. This approach helps to keep documentation up to date.

It's really simple if you use a monorepo. All docs and code are placed in one place, so it's easy to find what you need. Things become more complicated if you have lots of microrepos. Even if docs are up to date, it's quite hard for users to find them. Usually, this is solved by publishing docs to a central portal as part of the CI process, or nowadays by using an AI bot to help.

Recently, Pinterest published an article about how they adopted the documentation-as-code approach. Since they use microrepos, the main challenge was to make documentation discoverable for their users across hundreds of repos.

What they did:
🔸 Moved their docs to git repos using markdown.
🔸 Used MkDocs in CI to generate HTML versions of the docs.
🔸 Created a central place to host and index docs called PDocs (Pinterest Docs).
🔸 Integrated docs with GenAI — an AI bot connected to the main company communication channels.
🔸 Built a one-click tool to migrate old wiki pages to git.

I don’t know any standard solution for doc aggregation across multiple repos, so it would be great if Pinterest open-sourced their PDocs in the future. I think it could really help a lot of teams to improve their documentation processes.

#engineering #documentation