#65 Tech Writer broni docs as code, czyli klasyczne "u mnie działa"
"Docs as code" to filozofia, która głosi, żeby tworzyć dokumentację za pomocą tych samych narzędzi i procesów co oprogramowanie. W zamian za to otrzymujemy szereg benefitów, takich jak lepsza współpraca z programistami, synchronizacja kodu i dokumentacji, wersjonowanie, automatyczne testy oraz ogólne poczucie, że dokumentacja to wspólna odpowiedzialność.Czy takie podejście sprawdza się w praktyce? Czy nie są to tylko puste obietnice, których w rzeczywistości nie da się spełnić? W tym odcinku konfrontujemy artykuł "Docs as code is a broken promise" z naszymi własnymi doświadczeniami i przekonaniami. Uwaga, spoiler! Jako żarliwi zwolennicy docs as code, staramy się pokazać, że pomimo wyzwań jakie ze sobą niesie, jest to podejście, które dobrze się sprawdza w świecie dokumentacji do oprogramowania.Dźwięki wykorzystane w audycji pochodzą z kolekcji "107 Free Retro Game Sounds" dostępnej na stronie https://dominik-braun.net, udostępnianej na podstawie licencji Creative Commons license CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).Informacje dodatkowe: "Docs as code is a broken promise", Sarah Moir: https://thisisimportant.net/posts/docs-as-code-broken-promise/ "Docs as Code", Write the Docs: https://www.writethedocs.org/guide/docs-as-code/ "Documentation as Code: why you need it and how to get started", Swimm Team: https://swimm.io/learn/code-documentation/documentation-as-code-why-you-need-it-and-how-to-get-started Git: https://git-scm.com/ Subversion (SVN): https://subversion.apache.org/ Mercurial: https://www.mercurial-scm.org/ Perforce: https://www.perforce.com/solutions/version-control "What version control systems do you regularly use?", JetBrains: https://www.jetbrains.com/lp/devecosystem-2023/team-tools/#tools_vcs "Component content management system (CCMS)", Wikipedia: https://en.wikipedia.org/wiki/Component_content_management_system GitLab: https://gitlab.com/ GitHub: https://github.com/ The Zen of Python: https://peps.python.org/pep-0020/#the-zen-of-python MadCap Flare: https://www.madcapsoftware.com/products/flare/ Markdown: https://daringfireball.net/projects/markdown/ AsciiDoc: https://asciidoc.org/ Visual Studio Code (VS Code): https://code.visualstudio.com/ Kotlin: https://kotlinlang.org/ IntelliJ IDEA: https://www.jetbrains.com/idea/ "Emancipation: Why the heck would a tech writer use enterprise tools?", Paweł Kowaluk: https://meetcontent.github.io/events/krakow/2024/20 Docusuarus: https://docusaurus.io/ GitLens: https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens
Paweł Kowaluk przedstawia swoje zdanie na temat Docs as Code, wskazując, że jest za niego.
Kowaluk i Paweł Kowaluk dyskutują nad argumentami autorki artykułu, która twierdzi, że Docs as Code nie działa.
Kowaluk i Paweł Kowaluk omawiają narzędzie Git, jego złożoność oraz korzyści Docs as Code.
Kowaluk i Paweł Kowaluk analizują procesy w dokumentacji, argumentując za Docs as Code.
Kowaluk i Paweł Kowaluk poruszają temat merge gate'ów i sprawdzajek buildów, podkreślając ich znaczenie.
Kowaluk i Paweł Kowaluk podsumowują swoje przemyślenia nad Docs as Code, zakończając rozmowę.
Rozmowa o testach w dokumentacji i trudności review'u w narzędziach online.
Komentarze na temat trudności review'u dokumentacji bez dostępu do staging environment.
Diskussja o kosztach implementacji Docs as code i łatwości korzystania z nowszych CMSów.
Rozmowa na temat doświadczenia Tech Writerów w użyciu Docs as code i konieczności wsparcia technicznego.
Krytyka vendorów CCMS i ich obietnic, a także propozycja analizy przed implementacją Docs as code.
Rozdziały i streszczenia generowane automatycznie. Pełna transkrypcja nie jest publikowana — wyszukaj frazę, aby zobaczyć dopasowane fragmenty.
"Docs as code" to filozofia, która głosi, żeby tworzyć dokumentację za pomocą tych samych narzędzi i procesów co oprogramowanie. W zamian za to otrzymujemy szereg benefitów, takich jak lepsza współpraca z programistami, synchronizacja kodu i dokumentacji, wersjonowanie, automatyczne testy oraz ogólne poczucie, że dokumentacja to wspólna odpowiedzialność.
Czy takie podejście sprawdza się w praktyce? Czy nie są to tylko puste obietnice, których w rzeczywistości nie da się spełnić? W tym odcinku konfrontujemy artykuł "Docs as code is a broken promise" z naszymi własnymi doświadczeniami i przekonaniami. Uwaga, spoiler! Jako żarliwi zwolennicy docs as code, staramy się pokazać, że pomimo wyzwań jakie ze sobą niesie, jest to podejście, które dobrze się sprawdza w świecie dokumentacji do oprogramowania.
Dźwięki wykorzystane w audycji pochodzą z kolekcji "107 Free Retro Game Sounds" dostępnej na stronie https://dominik-braun.net, udostępnianej na podstawie licencji Creative Commons license CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).
Informacje dodatkowe:
"Docs as code is a broken promise", Sarah Moir: https://thisisimportant.net/posts/docs-as-code-broken-promise/ "Docs as Code", Write the Docs: https://www.writethedocs.org/guide/docs-as-code/ "Documentation as Code: why you need it and how to get started", Swimm Team: https://swimm.io/learn/code-documentation/documentation-as-code-why-you-need-it-and-how-to-get-started Git: https://git-scm.com/ Subversion (SVN): https://subversion.apache.org/ Mercurial: https://www.mercurial-scm.org/ Perforce: https://www.perforce.com/solutions/version-control "What version control systems do you regularly use?", JetBrains: https://www.jetbrains.com/lp/devecosystem-2023/team-tools/#tools_vcs "Component content management system (CCMS)", Wikipedia: https://en.wikipedia.org/wiki/Component_content_management_system GitLab: https://gitlab.com/ GitHub: https://github.com/ The Zen of Python: https://peps.python.org/pep-0020/#the-zen-of-python MadCap Flare: https://www.madcapsoftware.com/products/flare/ Markdown: https://daringfireball.net/projects/markdown/ AsciiDoc: https://asciidoc.org/ Visual Studio Code (VS Code): https://code.visualstudio.com/ Kotlin: https://kotlinlang.org/ IntelliJ IDEA: https://www.jetbrains.com/idea/ "Emancipation: Why the heck would a tech writer use enterprise tools?", Paweł Kowaluk: https://meetcontent.github.io/events/krakow/2024/20 Docusuarus: https://docusaurus.io/ GitLens: https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens