#65 Tech Writer broni docs as code, czyli klasyczne
"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 dominik-braun.net, udostępnianej na podstawie licencji Creative Commons license CC BY 4.0 (creativecommons.org/license...).
Informacje dodatkowe:
- "Docs as code is a broken promise", Sarah Moir: thisisimportant.net/posts/d...
- "Docs as Code", Write the Docs: www.writethedocs.org/guide/...
- "Documentation as Code: why you need it and how to get started", Swimm Team: swimm.io/learn/code-documen...
- Git: git-scm.com/
- Subversion (SVN): subversion.apache.org/
- Mercurial: www.mercurial-scm.org/
- Perforce: www.perforce.com/solutions/...
- "What version control systems do you regularly use?", JetBrains: www.jetbrains.com/lp/deveco...
- "Component content management system (CCMS)", Wikipedia: en.wikipedia.org/wiki/Compo...
- GitLab: gitlab.com/
- GitHub: github.com/
- The Zen of Python: peps.python.org/pep-0020/#t...
- MadCap Flare: www.madcapsoftware.com/prod...
- Markdown: daringfireball.net/projects...
- AsciiDoc: asciidoc.org/
- Visual Studio Code (VS Code): code.visualstudio.com/
- Kotlin: kotlinlang.org/
- IntelliJ IDEA: www.jetbrains.com/idea/
- "Emancipation: Why the heck would a tech writer use enterprise tools?", Paweł Kowaluk: meetcontent.github.io/event...
- Docusuarus: docusaurus.io/
- GitLens: marketplace.visualstudio.co...
