Tech Writer Koduje

AI jest wszędzie - w pracy, w szkole, w domu, a nawet w lodówce. Dlatego poczuliśmy się w obowiązku, żeby przyjrzeć się roli technoskryby w tym ciekawym momencie rozwoju technologicznego, w którym obecnie się znajdujemy.

Tempo rozwoju jest tak szybkie, że ten odcinek prawdopodobnie szybko przestanie być aktualny, jednak mamy nadzieję, że chociaż część naszych wniosków i przemyśleń pozostanie ponadczasowa. Rozmawiamy o tym jak sztuczna inteligencja wpływa na model pracy Tech Writera, co można zrobić przy pomocy dostępnych na tę chwilę narzędzi i jak zmienić podejście do pewnych kwestii związanych z tworzeniem dokumentacji, żeby wycisnąć ile się da z tej kolejnej już rewolucji technologicznej.

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/).

Linki:

• "Context engineering vs. prompt engineering: Key differences explained", Glean: https://www.glean.com/perspectives/context-engineering-vs-prompt-engineering-key-differences-explained  
• "What is agentic AI?", IBM: https://www.ibm.com/think/topics/agentic-ai
• Agent Skills: https://agentskills.io/home
• "Writing a good CLAUDE.md", HumanLayer Blog: https://www.humanlayer.dev/blog/writing-a-good-claude-md
• "New habits for tech writers in the age of LLMs", passo.uno: https://passo.uno/new-habits-tech-writers-ai-age/
• "The writing was always the cheap part", passo.uno: https://passo.uno/real-cost-of-documentation/
• GitHub Copilot: https://github.com/features/copilot
• Claude Code: https://claude.com/product/claude-code
• Elasticsearch: https://www.elastic.co/elasticsearch
• "AI slop", Wikipedia: https://en.wikipedia.org/wiki/AI_slop
• "Darwin Information Typing Architecture (DITA)", Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture 
• Oxygen XML Editor: https://www.oxygenxml.com/
• Oxygen AI Positron: https://www.oxygenxml.com/ai_positron.html
• "#57 Tech Writer zostaje Prompt Engineerem, czyli nowa potencjalna ścieżka kariery dla technoskryby", Tech Writer Koduje: https://techwriterkoduje.pl/blog/2023/8/28/57/

Trudno nie zgodzić się z tym, że tworzenie dokumentacji do oprogramowania wymaga wiedzy technicznej, szczególnie jeśli pracujesz w modelu docs as code. Natomiast trudno jest określić jaki poziom tej wiedzy powinien być. Czy jeśli pracuję z deweloperami to muszę znać ich narzędzia prawie tak samo dobrze jak oni? Czy wręcz odwrotnie - mogę się w ogóle nimi nie przejmować?

Jak zwykle prawda leży po środku. Powinno się znać te narzędzia na tyle na ile jest to potrzebne, żeby być lepszym technoskrybą - nie bardziej i nie mniej. W naszej rozmowie poszukujemy tego środka i dzielimy się naszymi praktycznymi wskazówkami, które sprawią, że zdobywanie wiedzy technicznej stanie się tylko środkiem do osiągnięcia Twojego celu a nie celem samym w sobie.

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/).

Linki:

• Arbortext: https://www.ptc.com/en/products/arbortext
• "Docs as Code", Write the Docs: https://www.writethedocs.org/guide/docs-as-code/
• "Jak pracować z narzędziami deweloperskimi - wskazówki dla tech writerów", techwriter.pl: https://techwriter.pl/jak-pracowac-z-narzedziami-nie-bedac-programista
• IntelliJ IDEA: https://www.jetbrains.com/idea/
• "Git (oprogramowanie)", Wikipedia: https://pl.wikipedia.org/wiki/Git_(oprogramowanie)
• Markdown: https://daringfireball.net/projects/markdown/syntax
• "Kurde! Reuse popsuł mi searcha", techwriter.pl: https://techwriter.pl/reuse-zly-dla-searcha/
• "Terminal", Filmweb: https://www.filmweb.pl/film/Terminal-2004-106408
• Visual Studio (VS) Code: https://code.visualstudio.com
• "CI/CD", Wikipedia: https://en.wikipedia.org/wiki/CI/CD
• "Wiersz poleceń", Wikipedia: https://pl.wikipedia.org/wiki/Wiersz_polece%C5%84
• Oxygen XML: https://www.oxygenxml.com/
• "Darwin Information Typing Architecture" (DITA), Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• AsciiDoc: https://asciidoc.org/
• reStructuredText: http://docutils.sourceforge.net/rst.html
• Static site generator: https://www.gatsbyjs.com/docs/glossary/static-site-generator/
• DITA Open Toolkit (DITA OT): https://www.dita-ot.org/
• "Component content management system (CCMS)", Wikipedia: https://en.wikipedia.org/wiki/Component_content_management_system
• Jamstack: https://jamstack.org/
• Yarn: https://yarnpkg.com/
• "What is Amazon S3", Amazon docs: https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html
• Wtyczka Prettier - Code formatter: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
• Wtyczka GitLens — Git supercharged: https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens
• Wtyczka Code Spell Checker: https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker
• "API", Wikipedia: https://en.wikipedia.org/wiki/API
• Wtyczka REST Client: https://marketplace.visualstudio.com/items?itemName=humao.rest-client
• Postman API client: https://www.postman.com/product/api-client/
• cURL: https://curl.se/
• „Ciemność, widzę ciemność, ciemność widzę - czyli jak poskromić linię komend", techwriter.pl: https://techwriter.pl/linia-komend

Od 2017 roku, na portalu techwriter.pl prowadzimy coroczne badanie płac. Po zebraniu odpowiedzi, publikujemy analizę wyników, która pozwala technoskrybom zobaczyć jak kształtuje się rynek komunikacji technicznej w Polsce pod kątem zarobków.

W momencie publikacji tego odcinka, ankieta za rok 2025 jest wciąż otwarta, ale my już teraz postanowiliśmy przyjrzeć się odpowiedziom, które do tej pory udało się nam zebrać. "Na gorąco" komentujemy wyniki i staramy się wyciągnąć z nich jakieś wnioski.

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/).

Linki:

• "Dziobak australijski", Wikipedia: https://pl.wikipedia.org/wiki/Dziobak_australijski
• "Wyniki badania płac w komunikacji technicznej 2024", techwriter.pl: https://techwriter.pl/wyniki-badania-plac-w-komunikacji-technicznej-2024/

Application Programming Interface (API) pozwala na komunikację pomiędzy programami. Ma ściśle określone reguły, które mówią nam w jaki sposób możemy zażądać informacji od jakiejś aplikacji i czego możemy spodziewać się w odpowiedzi.

Czy taka wiedza jest potrzebna Tech Writerom? Według nas jak najbardziej, szczególnie jeśli tworzą dokumentację dla deweloperów. Ten odcinek to podsumowanie wiedzy jaką przekazaliśmy uczestnikom podczas darmowych warsztatów "Using REST APIs for Technical Writers", które przeprowadziliśmy 28.11.2025 przy współpracy z Content Bytes.

Rozmawiamy o tym czym jest API, jak sformułować żądanie, które pozwoli nam otrzymać odpowiedź, jakie typy żądań i odpowiedzi istnieją, jakich narzędzi możemy użyć i o innych podstawach, które ułatwią technoskrybom wejście w świat interakcji z aplikacjami poprzez API.

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/).

Linki:

• CAKE conf: https://cakeconf.contentbytes.pl/
• "API", Wikipedia: https://en.wikipedia.org/wiki/API
• "What Is a REST API? Examples, Uses, and Challenges", Postman Blog: https://blog.postman.com/rest-api-examples/
• "SOAP", Wikipedia: https://en.wikipedia.org/wiki/SOAP
• Swagger UI: https://swagger.io/tools/swagger-ui/
• OpenAPI: https://www.openapis.org/
• cURL: https://curl.se/
• Visual Studio (VS) Code: https://code.visualstudio.com
• REST Client: https://marketplace.visualstudio.com/items?itemName=humao.rest-client
• Postman API client: https://www.postman.com/product/api-client/
• Requestly: https://requestly.com/

Każdy z nas może zmienić świat na lepsze. Jednym ze sposobów jest na pewno udział w projekcie "Hakersi", którego celem jest wyrównywanie szans edukacyjnych i wspieranie w usamodzielnianiu się poprzez naukę nowych technologii i rozwijanie przydatnych kompetencji.

Angażując się w ten projekt masz realny wpływ na życie młodych ludzi z placówek opiekuńczo-wychowawczych, pieczy zastępczej i świetlic środowiskowych.

Z Katarzyną Klimek-Michno, ekspertką ds. komunikacji i PR w Fundacji Sarigato, omawiamy szczegółowo projekt "Hakersi". Z naszej rozmowy dowiecie się na czym on polega, kto za nim stoi, kto i jak może go wesprzeć, jakie są bieżące potrzeby i plany na przyszłość. Usłyszycie też inspirujące historie, które mamy nadzieję, zachęcą Was do działania.

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/).

Linki:

• Projekt "Hakersi": https://hakersi.pl/
• Fundacja Sarigato: https://sarigato.org/
• Hack4Krak: https://hack4krak.pl/
• Katarzyna Klimek-Michno, LinkedIn: https://www.linkedin.com/in/katarzyna-klimek-michno-567a7bb3/

"Feedback" to takie ciekawe, pojemne i skomplikowane zagadnienie. Po pierwsze, ciężko je przetłumaczyć dobrze na język polski. Niestety, słowa takie jak "krytyka", "recenzja" albo "opinia" nie niosą ze sobą takiego ładunku jak oryginał. Po drugie, zarówno dawanie jak i przyjmowanie feedbacku we właściwy sposób to nie lada sztuka, którą nie łatwo jest opanować. Ta z pozoru prosta czynność ma tak wiele ruchomych części, które mogą wskoczyć na niewłaściwe miejsce powodując różnej maści problemy.

Do rozmowy na temat feedbacku zaprosiliśmy naszą znajomą po fachu Aleksandrę Wieczorek-Konieczko, która obecnie realizuje się jako konsultantka "uzdrawiająca dokumentację" (DocDoctor). Analizujemy to zagadnienie z perspektywy sytuacji, które często występują w branży IT starając się znaleźć odpowiedź na pytanie "Jak to robić dobrze?".

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/).

Linki:

• "Doktorka od dokumentacji: Rozmowa z Olą o tech writingu i łączeniu kreatywności z wiedzą techniczną", Freelance Superstars: https://creators.spotify.com/pod/profile/freelancesuperstars/episodes/Doktorka-od-dokumentacji-Rozmowa-z-Ol-o-tech-writingu-i-czeniu-kreatywnoci-z-wiedz-techniczn-e38rvui/a-ac6c822
• "#74 Tech Writer poszukuje clou swojej pracy, czyli za co nam płacą", Tech Writer Koduje: https://techwriterkoduje.pl/blog/2025/1/29/74/
• "About pull requests", GitHub: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
• CAKE conf: https://cakeconf.contentbytes.pl/
• "Syndrom oszusta", Wikipedia: https://pl.wikipedia.org/wiki/Syndrom_oszusta
• Aleksandra Wieczorek-Konieczko, LinkedIn: https://www.linkedin.com/in/techwriter-wieczorek/
• DocDoctor: https://www.doc-doctor.org/

Zapewne każdy programista zna albo przynajmniej słyszał o Visual Studio Code (VS Code), czyli darmowym edytorze ze stajni Microsoftu.

Jednak podejrzewamy, że nie każdy Tech Writer wie co to za narzędzie i że można go z powodzeniem używać do tworzenia dokumentacji. Raczej nie przyda nam się jeśli pracujemy z narzędziami typu CCMS, ale za to doskonale sprawdzi się w modelu "docs as code", w którym niepodzielnie od wielu lat króluje Markdown. Mnogość opcji konfiguracyjnych i dostępnych wtyczek sprawia, że ten edytor może okazać się świetnym wyborem dla technoskrybów, którzy ściśle współpracują z programistami.

Rozmawiamy o tym co nam oferuje VS Code, jakie wtyczki przydają się do pisania dokumentacji, jakie ciekawe funkcje można znaleźć w tym edytorze, a nawet o tym jak dodać podstawowe wsparcie dla plików DITA.

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/).

Linki:

• Visual Studio Code (VS Code): https://code.visualstudio.com/https://code.visualstudio.com/
• Wtyczka MDX: https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx

• Wtyczka Markdown All in One: https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
• Wtyczka markdownlint: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
• Wtyczka Markdown Preview Enhanced: https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced
• Vale: https://github.com/errata-ai/vale
• Wtyczka Vale VSCode: https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode
• Wtyczka Write Good Linter: https://marketplace.visualstudio.com/items?itemName=travisthetechie.write-good-linter
• Wtyczka vscode-textlint: https://marketplace.visualstudio.com/items?itemName=taichi.vscode-textlint
• Wtyczka Prettier - Code formatter: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
• Wtyczka Code Spell Checker: https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker
• Wtyczka Markdown PDF: https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf
• Wtyczka Gremlins tracker for Visual Studio Code: https://marketplace.visualstudio.com/items?itemName=nhoizey.gremlins
• Wtyczka REST Client: https://marketplace.visualstudio.com/items?itemName=humao.rest-client
• Wtyczka GitLens — Git supercharged: https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens

• "Lint, Lint and Away! Linters for the English Language", Chris Chinchilla: https://hackernoon.com/lint-lint-and-away-linters-for-the-english-language-70f4b22cc73c
• "The 2025 Developer Survey", Stack Overflow: https://survey.stackoverflow.co/2025

• "Darwin Information Typing Architecture" (DITA), Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• "How can I make DITA catalog.xml work in VS Code?", Stack Overflow: https://stackoverflow.com/questions/64782816/how-can-i-make-dita-catalog-xml-work-in-vs-code

Cały rok pracujesz w pocie czoła w przekonaniu, że Twoja praca ma sens i generuje wartość dla firmy. Zapewne masz rację, ale nie oznacza to, że osoby usytuowane wyżej w hierarchii są tego świadome i rozumieją złożoność tego z czym musisz się mierzyć na co dzień. Dlatego szefostwo organizuje wszelkiej maści spotkania i prezentacje, szczególnie na koniec roku fiskalnego, które są dla Ciebie niepowtarzalną szansą na przedstawienie swojego bogatego dorobku.

Rozmawiamy o tym jak pokazać przełożonym wartość swojej pracy, tak żeby po 5 minutach nie stracili zainteresowania, na ile głęboko powinniśmy wchodzić w szczegóły techniczne i jakie cyferki mają znaczenie. W pierwszej części omawiamy wspomniane zagadnienia z punktu widzenia Doc Tools Developera, a w drugiej z punktu widzenia Tech Writera.

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/).

Od niedawna mamy możliwość korzystania w pracy z pomocy sztucznej inteligencji, a konkretnie GitHub Copilota.

Rozmawiamy o tym jak działa to narzędzie, jakie ma możliwości i w jaki sposób zmienia naszą pracę. Omawiamy konkretne przykłady zastosowania drugiego pilota w kodowaniu i tworzeniu dokumentacji i staramy się ocenić czy w ogólnym rozrachunku jest on dla nas pomocą, utrudnieniem czy zagrożeniem.

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:

• GitHub Copilot: https://github.com/features/copilot
• "Agentic AI", Wikipedia: https://en.wikipedia.org/wiki/Agentic_AI
• "Darwin Information Typing Architecture", Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• "AI Changes Everything", Armin Ronacher: https://lucumr.pocoo.org/2025/6/4/changes/
• "My AI Skeptic Friends Are All Nuts", Thomas Ptacek: https://fly.io/blog/youre-all-nuts/
• "Agent AI - kopilot dla tech writera", Paweł Kowaluk: https://techwriter.pl/copilot-dla-tech-writera
• "#57 Tech Writer zostaje Prompt Engineerem, czyli nowa potencjalna ścieżka kariery dla technoskryby", Tech Writer Koduje: https://techwriterkoduje.pl/blog/2023/8/28/57

Co mają ze sobą wspólnego wędkarze i technoskryby? I nie chodzi o nam o słowo "ryby". To, że mogą stworzyć społeczność, która będzie się spotykać, wymieniać doświadczeniami i wspierać w trudnych momentach.

Ale jak sprawić, żeby taka społeczność powstała? Odpowiedź wydaje się prosta - dać ludziom przestrzeń do spotkań, zrobić prezentację i nakarmić. Jednak w rzeczywistości wymaga to zdecydowanie więcej wysiłku.

Rozmawiamy z Edytą Rakowską i Basią Czyż z Content Bytes o cieniach i blaskach organizowania meetupów dla specjalistów zajmujących się szeroko pojętą treścią, o tym co je motywuje do działania, dlaczego warto dołączyć jako uczestnik i prelegent oraz o ich planach na przyszłość.

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:

• Content Bytes: https://contentbytes.pl/
• CAKE Conf: https://cakeconf.contentbytes.pl/
• Content Bytes #04 - "Let's talk language": https://contentbytes.pl/events/2025/4
• Michał Olender, LinkedIn: https://www.linkedin.com/in/michal-olender/
• Paweł Chłodnicki, LinkedIn: https://www.linkedin.com/in/pawelchlodnicki/
• Tomasz Prus, LinkedIn: https://www.linkedin.com/in/tomasz-prus-4b09b01a/
• Slack: https://slack.com/
• Linear: https://linear.app/

Mówi się, że zanim zaczniemy biegać musimy nauczyć się chodzić. W tej mądrości ludowej kryje się wiele prawdy, którą można zastosować do nauki jakiegokolwiek zagadnienia, np. systemu kontroli wersji Git.

Powierzchowna znajomość Gita i jego najpopularniejszych komend może nam zapewnić spokój na całkiem długi czas, ale w pewnym momencie zaczniemy dostrzegać trudności w radzeniu sobie z pewnymi sytuacjami. Niechlujne wpisy w historii zmian na pewno utrudnią nam ustalenie kto, kiedy i dlaczego coś zmienił, a brak znajomości podstawowych zagadnień i mechaniki Gita spowoduje, że nieraz poczujemy się zagubieni i bezradni.

Rozmawiamy o tym jak zadbać o to, żeby nasza historia zmian była jasna i przejrzysta, a przez to przydatna i z jakiego zakresu uzupełnić wiedzę teoretyczną o Gicie, a także dzielimy się wskazówkami na temat przydatnych ustawień i komend.

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:

• Git: https://git-scm.com/
• "How to Write a Git Commit Message", cbeams: https://cbea.ms/git-commit/
• "Git turns 20: A Q&A with Linus Torvalds", GitHub: https://github.blog/open-source/git/git-turns-20-a-qa-with-linus-torvalds/
• "How did Git get its name?", Initial Commit: https://initialcommit.com/blog/How-Did-Git-Get-Its-Name
• Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0/
• "Darwin Information Typing Architecture (DITA)", Wikipedia: https://pl.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• "Git Squash Commits: A Guide With Examples", DataCamp: https://www.datacamp.com/tutorial/git-squash-commits
• "How to Create and Push an Empty Commit in Git", Tower FAQ: https://www.git-tower.com/learn/git/faq/git-empty-commit
• "8.1 Customizing Git - Git Configuration", Git: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration

Naszym zdaniem otwarty umysł to bardzo przydatna cecha. Idea otwartości w połączeniu z działaniem na rzecz wspólnego dobra to nic innego jak "open source".

Projekty z obszaru wolnego i otwartego oprogramowania przynoszą wielu organizacjom i jednostkom niebagatelne korzyści. Pomimo tego, że większość z nas jest świadoma ich ogromnej wartości, zazwyczaj borykają się one z problemem braku rąk do pracy. Cierpi na tym nie tylko kod, ale też dokumentacja. I to bardzo.

Z naszym gościem, Łukaszem Górnickim, staramy się Wam przybliżyć wyjątkowy świat "open source". Rozmawiamy o tym czym jest wolne i otwarte oprogramowanie, jakimi prawami się rządzi i jak wygląda praca w projektach "open source", dlaczego warto do nich dołączyć i jak to zrobić. A to wszystko z perpektywy Tech Writera.

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:

• "Open-source software", Wikipedia: https://en.wikipedia.org/wiki/Open-source_software
• "FLOSS and FOSS", Richard Stallman: https://www.gnu.org/philosophy/floss-and-foss.en.html
• Open Source Initiative (OSI): https://opensource.org/
• Google Season of Docs: https://developers.google.com/season-of-docs
• Outreachy: https://www.outreachy.org/
• Kubernetes: https://kubernetes.io/
• Postman: https://www.postman.com/
• AsyncAPI: https://www.asyncapi.com/en
• "VMware Sued over Alleged Open Source License Violation in Linux", Sean Michael Kerner: https://www.datamation.com/open-source/vmware-sued-over-alleged-open-source-license-violation-in-linux/
• Git: https://git-scm.com/
• GitHub (vel "Instagram dla deweloperów"): https://github.com/
• Techwriter.pl: https://techwriter.pl/
• Open Source Program Office (OSPO): https://github.com/todogroup/ospodefinition.org
• OSPOs for good 2024 conference report: https://www.un.org/digital-emerging-technologies/sites/www.un.org.techenvoy/files/OPSOs_for_Good_2024_Conference_Report.pdf
• "The European Organization for Nuclear Research (CERN) ": https://en.wikipedia.org/wiki/CERN
• OpenForum Europe (OFE): https://openforumeurope.org/about-ofe/
• Capital Series Poland: https://openforumeurope.org/event/capital-series-poland/
• Bielik LLM: https://bielik.ai/
• Brain Fart Services: https://www.brainfart.dev/

W komunikacji technicznej (i nie tylko) występuje zjawisko ustrukturyzowanego tworzenia treści, czyli "structured writing" albo jak kto woli "structured authoring". Cała idea sprowadza się do stworzenia zasad, które są potem stosowane w trakcie pisania. Poprzez narzucenie takich ściśle określonych reguł jesteśmy w stanie dostarczać treść, która jest lepszej jakości i którą nasi odbiorcy są w stanie łatwiej i szybciej konsumować.

"Structured writing" to złożone zagadnienie. Mnogość zalet przeplata się tutaj z równie dużą liczbą wyzwań.

Rozmawiamy o tym czym jest ustrukturyzowane tworzenie treści, co nam daje, w czym nam pomaga a w czym przeszkadza oraz jakich standardów i narzędzi możemy użyć do jego wdrożenia w organizacji.

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:

• "Structured writing", Wikipedia: https://en.wikipedia.org/wiki/Structured_writing
• "Structured authoring in technical documentation: an overview", Author-it blog: https://www.author-it.com/blog/structured-authoring-in-technical-documentation/
• "What is Structured Writing?", Mark Baker: https://techwhirl.com/what-is-structured-writing/
• "Topic-based authoring", Wikipedia: https://en.wikipedia.org/wiki/Topic-based_authoring
• "Darwin Information Typing Architecture", Wikipedia (DITA): https://pl.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• "Markdown", Wikipedia: https://pl.wikipedia.org/wiki/Markdown
• "The path to structured content with Markdown", Niklas Begley: https://www.doctave.com/blog/path-to-structured-markdown
• Semantic Authoring Markdown (sam): https://github.com/mbakeranalecta/sam
• Semantic Markdown: https://hackmd.io/@sparna/semantic-markdown-draft#What-is-Semantic-Markdown
• Markdoc: https://markdoc.dev/
• MDX: https://mdxjs.com/
• Lightweight DITA: https://docs.oasis-open.org/dita/LwDITA/v1.0/cnprd01/LwDITA-v1.0-cnprd01.html
• HyperText Markup Language (HTML): https://developer.mozilla.org/en-US/docs/Web/HTML

Kiedy Tech Writer nie koduje, zaczyna rozważać nad swoją egzystencją, a dokładniej nad tym jaką unikalną wartość wnosi jego praca.

Nie jest łatwo odpowiedzieć na pytanie jakie jest clou pracy Tech Writera, dlatego o pomoc poprosiliśmy Aleksandrę Wieczorek-Konieczko, która ma kilka lat różnorodnego doświadczenia w branży komunikacji technicznej i sporo przemyśleń na ten temat. Wspólnie zastanawiamy się za co nam tak naprawdę płacą i dlaczego naszej pracy nie może wykonywać ktoś inny z równie dobrym skutkiem.

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:

• Passo uno, Fabrizio Ferri Benedetti: https://passo.uno/
• "The Seven-Action Documentation model", Fabrizio Ferri Benedetti: https://passo.uno/seven-action-model/
• "Your docs are your infrastructure", The Stack Overflow Podcast: https://stackoverflow.blog/2024/11/26/your-docs-are-your-infrastructure/
• "Czy dobra aplikacja potrzebuje instrukcji", Michał Skowron: https://www.slideshare.net/slideshow/czy-dobra-aplikacja-potrzebuje-instrukcji/83832453
• Aleksandra Wieczorek-Konieczko, LinkedIn: https://pl.linkedin.com/in/techwriter-wieczorek

Rok 2024 w komunikacji technicznej i w naszej pracy obfitował w ciekawe wydarzenia i projekty. Na naszych oczach powstawały nowe organizacje i inicjatywy, tworzyły się nowe trendy, a rzeczywistość technologiczna zmusiła nas do eksplorowania różnych rozwiązań. Krótko mówiąc, działo się!

Dlatego, podążając za trendem wyznaczonym przez Spotify, postanowiliśmy stworzyć tech commowy Wrapped. Jest to nasze subiektywne podsumowanie najważniejszych rzeczy, które miały miejsce w komunikacji technicznej i w naszym życiu zawodowym w mijającym roku.

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:

• Content Bytes (LinkedIn): https://www.linkedin.com/company/content-bytes
• "Content Bytes - nowe oblicze spotkań dla specjalistów od treści", techwriter.pl: https://techwriter.pl/content-bytes-promo/
• SAiIT (LinkedIn): https://www.linkedin.com/in/saiit-polska-03a008308/
• "Stowarzyszenie Autorów i Ilustratorów Technicznych (SAIiT) - Wywiad z Łukaszem Rybką", techwriter.pl: https://techwriter.pl/saiit-wywiad/
• "Stowarzyszenie Autorów i Ilustratorów Technicznych (SAiIT) - Spotkanie założycielskie", techwriter.pl: https://techwriter.pl/saiit-spotkanie-zalozycielskie/
• "Stowarzyszenie Autorów i Ilustratorów Technicznych (SAiIT) - Początki działalności", techwriter.pl: https://techwriter.pl/saiit-spotkanie-zalozycielskie-relacja
• soap! technical communication (LinkedIn): https://www.linkedin.com/company/soap-techcomm
• "#63 Tech Writer poznaje moc języka w produktach cyfrowych, czyli dlaczego UX writing jest ważny", Tech Writer Koduje: https://techwriterkoduje.pl/blog/2024/2/26/63
• "UX writing. Moc języka w produktach cyfrowych", Wojciech Aleksander (Onepress): https://onepress.pl/ksiazki/ux-writing-moc-jezyka-w-produktach-cyfrowych-wojciech-aleksander,uxwri.htm
• "Badanie płac w komunikacji technicznej 2024 – wypełnij ankietę!", techwriter.pl: https://techwriter.pl/badanie-plac-w-komunikacji-technicznej-2024
• Artykuły, Tech Writer koduje: https://techwriterkoduje.pl/read
• MeetContent: https://meetcontent.github.io/
• Web Summer Camp: https://websummercamp.com/2025
• Passo uno, Fabrizio Ferri Benedetti: https://passo.uno/
• "#71 Tech Writer rozlicza się z semantic searcha, czyli plany kontra rzeczywistość", Tech Writer Koduje: https://techwriterkoduje.pl/blog/2024/10/28/71
• Adrian Wyka (LinkedIn): https://www.linkedin.com/in/adrianwyka/
• Accens (LinkedIn): https://www.linkedin.com/company/accens
• Zbójcerze Dostępności Kupują Prezenty (YouTube): https://www.youtube.com/playlist?list=PLrKAuW72u41T7PpjAshgiwspD9UCILIvU
• "#16 DITA z Gita", Tech Writer koduje: https://techwriterkoduje.pl/blog/2020/4/22/16

W przeszłości wielokrotnie dzieliliśmy się naszymi przemyśleniami na temat docs as code i CCMSów. Dlatego zamiast po raz kolejny głosić nasze zamiłowanie do rozwiązań niepochodzących od vendorów, postanowiliśmy zapytać innych o ich doświadczenia.

Udało nam się znaleźć kilka osób, które uczestniczyły w migracji z CCMSa do docs as code i zgodziły się nam opowiedzieć o tym czy nowe rozwiązanie okazało się lekiem na całe zło czy gorzkim rozczarowaniem.

Rozmawiamy o tym dlaczego ludzie porzucają CCMSy, oraz o wyzwaniach, niespełnionych oczekiwaniach i benefitach, czasem nieoczywistych, związanych z przejściem na docs as code.

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:

• "#65 Tech Writer broni docs as code, czyli klasyczne "u mnie działa"", Tech Writer Koduje: https://techwriterkoduje.pl/blog/2024/4/29/65
• "Are people abandoning docs as code?", Paweł Kowaluk: https://techwriterkoduje.pl/abandon-docs-as-code
• "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
• "Component content management system (CCMS)", Wikipedia: https://en.wikipedia.org/wiki/Component_content_management_system
• Git: https://git-scm.com/
• Markdown: https://daringfireball.net/projects/markdown/
• DITA (Darwin Information Typing Architecture): https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• DITA Open Toolkit (DITA OT): https://www.dita-ot.org/

Prawie rok temu zabraliśmy się za wdrożenie semantic searcha. Byliśmy bardzo podekscytowani tym projektem, bo po długich miesiącach teoretyzowania na ten temat wreszcie udało nam się stworzyć rozwiązanie pilotażowe, które mogliśmy pokazać testowej grupie użytkowników.

Zgodnie z obietnicą złożoną w odcinku 61. wracamy do tego projektu. Rozmawiamy o tym jak się potoczyły jego losy, jakie były wyniki testów, jakie wyciągnęliśmy wnioski i co planujemy w przyszłości.

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:

• "#61 Tech Writer zaczyna wdrażać semantic search, czyli kilka praktycznych wskazówek na początek", Tech Writer Koduje: https://techwriterkoduje.pl/blog/2023/12/22/61
• "What is semantic search?", Elastic: https://www.elastic.co/what-is/semantic-search
• "Large language model (LLM)", Wikipedia: https://en.wikipedia.org/wiki/Large_language_model
• "What Is Retrieval-Augmented Generation, aka RAG?", NVIDIA Blogs: https://blogs.nvidia.com/blog/what-is-retrieval-augmented-generation/
• "Hybrid Search Explained", Weaviate: https://weaviate.io/blog/hybrid-search-explained
• Hugging Face: https://huggingface.co/
• "Semantic search", SBERT: https://www.sbert.net/examples/applications/semantic-search/README.html#semantic-search

Po prawie 5 latach, ponownie zagościła u nas Agata Rygielska. Tym razem rozmawialiśmy o jej drodze od tłumaczki do kodującej Tech Writerki. Agata opowiedziała nam dlaczego postanowiła rozwijać swoje umiejętności techniczne, jakich języków i technologii się uczyła, w jaki sposób nabywała wiedzę, jakie były dla niej największe wyzwania oraz jakie ma plany na przyszłość.

Na koniec dzielimy się wynikami krótkiej ankiety na temat kodowania, którą przeprowadziliśmy wśród Tech Writerów. Dowiecie się z niej m.in. jaki procent ankietowanych koduje a jaki zna rożnicę między Javą i JavaScriptem.

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:

• "#11 Robot dokumentuje część 2 - automatyzacja kontra ludzie", Tech Writer Koduje: https://techwriterkoduje.pl/blog/2019/12/12/11
• "Optimus - ofiara chorego systemu, który od lat niszczy polską przedsiębiorczość": https://forsal.pl/artykuly/780660,optimus-ofiara-chorego-systemu-ktory-od-lat-niszczy-polska-przedsiebiorczosc.html
• MadCap Flare: https://www.madcapsoftware.com/products/flare/
• React: https://react.dev/
• Docker: https://www.docker.com/
• "#27 Tech Writer szkoli się z Pythona", Tech Writer Koduje: https://techwriterkoduje.pl/blog/2021/2/17/27
• lxml: https://lxml.de/
• Jenkins: https://www.jenkins.io/
• Babel: https://babeljs.io/
• Rollup: https://rollupjs.org/
• Git: https://git-scm.com/
• Cursor AI: https://www.cursor.com/
• Notepad++: https://notepad-plus-plus.org/
• Visual Studio Code: https://code.visualstudio.com/
• Strona Sebastiana Witowskiego: https://switowski.com/
• "Modern Python Projects Course", Talk Python to Me: https://training.talkpython.fm/courses/modern-python-projects
• PyCharm: https://www.jetbrains.com/pycharm/
• Vale: https://github.com/errata-ai/vale
• Static site generator: https://www.gatsbyjs.com/docs/glossary/static-site-generator/
• "What is CodeWhisperer?", Amazon AWS Documentation: https://docs.aws.amazon.com/codewhisperer/latest/userguide/what-is-cwspr.html
• "Cascading Style Sheets", Wikipedia: https://simple.wikipedia.org/wiki/Cascading_Style_Sheets
• Sourcery: https://sourcery.ai/
• Kotlin: https://kotlinlang.org/
• Vasont CMS: https://www.globallinkccms.com/products/vasont
• "C Sharp (programming language)", Wikipedia: https://en.wikipedia.org/wiki/C_Sharp_(programming_language)
• "XSL Formatting Objects", Wikipedia: https://pl.wikipedia.org/wiki/XSL_Formatting_Objects
• Pykonik, Kraków Python User Group: https://www.meetup.com/pl-PL/pykonik/

Pisanie dobrej dokumentacji dla deweloperów oprócz wysoko rozwiniętego warsztatu językowego wymaga również umiejętności technicznych, takich jak kodowanie.

Czy teoretyczna znajomość pewnych zagadnień jest wystarczająca czy trzeba również posiadać doświadczenie praktyczne?

Rozmawiamy o tym jak bardzo zaawansowane umiejętności techniczne powinien posiadać technoskryba w świecie rozwoju oprogramowania i czego powinien się nauczyć, żeby brylować na deweloperskich salonach i tworzyć dokumentację o wysokiej jakości i wiarygodności.

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:

• React.js: https://react.dev/
• "Git (oprogramowanie)", Wikipedia: https://pl.wikipedia.org/wiki/Git_(oprogramowanie)
• "Git Amend", W3Schools: https://www.w3schools.com/git/git_amend.asp?remote=github
• GitHub: https://github.com/
• "JavaScript", Wikipedia: https://pl.wikipedia.org/wiki/JavaScript
• "Java", Wikipedia: https://pl.wikipedia.org/wiki/Java
• Docker: https://www.docker.com/
• Docker Compose overview: https://docs.docker.com/compose/
• "Docker image vs container: What are the differences?", CircleCI: https://circleci.com/blog/docker-image-vs-container/
• "Why is Python a dynamic language and also a strongly typed language": https://wiki.python.org/moin/Why%20is%20Python%20a%20dynamic%20language%20and%20also%20a%20strongly%20typed%20language
• Kubernetes: https://kubernetes.io/
• "How to Launch an HTTP Server in One Line of Python Code", Real Python: https://realpython.com/python-http-server/
• Npm serve: https://www.npmjs.com/package/serve
• REST Client, VS Code: https://marketplace.visualstudio.com/items?itemName=humao.rest-client
• HTTP Client, IntelliJ IDEA: https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html
• curl: https://curl.se/
• Postman: https://www.postman.com/
• "bash", Wikipedia: https://pl.wikipedia.org/wiki/Bash

Pisanie dokumentacji jest trudne, co do tego nie mamy wątpliwości. Programiści nie raz w swojej karierze napotykają sytuację, w której muszą opisać jakąś procedurę lub stworzyć README. O ile aktualizacja istniejącej dokumentacji jest do przejścia, to napisanie czegoś od zera może wydawać się zadaniem nie do wykonania.

Czy na pewno? Okazuje się, że deweloperzy mogą wiedzieć więcej o pisaniu dokumentacji niż im się wydaje. Wystarczy tylko zmienić sposób myślenia na temat tego procesu i poznać kilka podstawowych zasad tech writingu.

W naszej rozmowie łączymy filozoficzne rozważania o podobieństwach pomiędzy kodowaniem i pisaniem dokumentacji z praktycznymi wskazówkami dla programistów na temat pisania dokumentacji.

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:

• Konferencja Web Summer Camp: https://websummercamp.com
• "Democratizing Design for Better Collaboration", Stephanie Stimac: https://www.youtube.com/watch?v=ZATMLWKIObA&list=PLsL1X_98-_XDD1Lm32Sk8HPyPgZ0e1JeX&index=3
• "Guard Clause", DevIQ: https://deviq.com/design-patterns/guard-clause
• Colima: https://github.com/abiosoft/colima
• "#67 Tech Writer żegna "foo", "bar" i "baz", czyli jak tworzyć dobre próbki kodu", Tech Writer koduje: https://techwriterkoduje.pl/blog/2024/6/26/67
• "Structured writing", Wikipedia: https://en.wikipedia.org/wiki/Structured_writing
• "Golden rules for writing docs", Tech Writer koduje: https://techwriterkoduje.pl/golden-rules
• "How did over 300 skeptics start writing docs?", Rafał Pawlicki (soap! 2018): https://www.youtube.com/watch?v=FpcSJa5rEpE
• "Style guide, czyli księga stylu: jak trzymać fason w UX writingu", UX Writing Wiwisekcja: https://open.spotify.com/episode/4jGjLxt8igNqOCmgb8tOmi?si=33167b19519549bb
• "Top 10 tips for Microsoft style and voice", Microsoft Writing Style Guide: https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice
• "Software Engineering at Google", Titus Winters, Tom Manshreck, Hyrum Wright: https://www.oreilly.com/library/view/software-engineering-at/9781492082781/

Próbki kodu to kluczowy element dokumentacji, a w szczególności dokumentacji dla deweloperów. Dlatego uważamy, że "foo", "bar" i "baz" muszą odejść.

Jako kodujący Tech Writerzy spotykamy się zarówno z dobrymi jak i kiepskimi przykładami, dlatego postanowiliśmy podsumować naszą wiedzę i doświadczenia w tym zakresie i zastanowić się jak tworzyć próbki, które są pomocne i łatwe do zrozumienia.

Rozmawiamy o dobrych i złych praktykach, o potencjalnych problemach i rozwiązaniach oraz, oczywiście, o narzędziach, które możemy wykorzystać, żeby nasze próbki były jeszcze lepsze.

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:

• "Never Use Foo, Bar, Baz, etc. in Software Documentation", Tech Your Chance: https://www.techyourchance.com/never-use-foo-bar-baz/
• "Online resources to learn how to code", StackOverflow Developer Survey 2022: https://survey.stackoverflow.co/2022/#section-learning-to-code-online-resources-to-learn-how-to-code
• "Online resources to learn how to code", StackOverflow Developer Survey 2023: https://survey.stackoverflow.co/2023/#section-learning-to-code-online-resources-to-learn-how-to-code
• "Default behaviour sticks (And so do examples)", Thinkst Thoughts: https://blog.thinkst.com/2023/08/default-behaviour-sticks-and-so-do-examples.html
• "Code blocks", Docusaurus: https://docusaurus.io/docs/markdown-features/code-blocks
• rundoc: https://eclecticiq.github.io/rundoc/
• "Code samples", Google developer documentation style guide: https://developers.google.com/style/code-samples
• "Creating sample code", Google Technical Writing: https://developers.google.com/tech-writing/two/sample-code
• "Guidelines for writing code examples", MDN: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
• "Write excellent code examples", The Developer Advocacy Handbook: https://developer-advocacy.com/write-excellent-code-examples
• Dokumentacja React.js: https://react.dev/
• Dokumentacja Yarn: https://yarnpkg.com/
• Dokumentacja react-router: https://reactrouter.com/en/main
• Prism.js: https://prismjs.com/
• Docusaurus: https://docusaurus.io/
• Storybook: https://storybook.js.org/

W tym miesiącu nasz podcast obchodzi 5. urodziny. Przez ten czas nagraliśmy ponad 60 odcinków, w których rozmawialiśmy o wielu rzeczach związanych z techniczną stroną tworzenia dokumentacji, ale nigdy o tym co się dzieje za kotarą, o naszych tajnikach i technikach.

Dlatego z okazji jubileuszu, postanowiliśmy opowiedzieć Wam dlaczego w ogóle zaczęliśmy nagrywać, skąd czerpiemy pomysły, czy pracujemy ze scenariuszem czy raczej jesteśmy mistrzami improwizacji, jakiego sprzętu i oprogramowania używamy, jak działa nasza strona i czy w ogóle ktoś nas słucha.

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:

• "#1 Docs like code - rozważania praktyczne i filozoficzne", Tech Writer koduje: https://techwriterkoduje.pl/blog/2019/5/14/1
• "Polski podkast dla techwriterów!", Techwriter.pl: https://techwriter.pl/polski-podkast-dla-techwriterow/
• Riverside.fm: https://riverside.fm/
• Zencastr: https://zencastr.com/
• Audacity: https://www.audacityteam.org/
• Spotify for Podcasters (dawniej Anchor.fm): https://podcasters.spotify.com/
• "RSS", Wikipedia: https://pl.wikipedia.org/wiki/RSS
• Mikrofon Novox NC-1: https://novox.pl/
• "#51 Tech Writer buduje stronę dla podcastu, czyli praktyczne zastosowanie Next.js", Tech Writer koduje: https://techwriterkoduje.pl/blog/2023/2/26/51
• "MeetContentKRK zaprasza na Content Day", techwriter.pl: https://techwriter.pl/meet-content-krk-content-day/

"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

Standard DITA, czyli Darwin Information Typing Architecture, nie jest zły sam w sobie, ale może skłaniać nas do stosowania pewnych praktyk, które wpływają negatywnie na wyszukiwanie. Przykładem mogą być strony, które mają bardzo mało treści, przez co nie są zbyt pomocne, a jednocześnie zabierają cenne miejsce na liście wyników wyszukiwania. Kolejną kwestią jest ponownie wykorzystanie treści, czyli reuse. Jest to temat szeroki a problemy z nim związane dotyczą nie tylko standardu DITA.

Rozmawiamy o tym co powoduje, że wyniki wyszukiwania nie są pomocne, złych praktykach w tworzeniu dokumentacji w wersji webowej, problemach z reusem i potencjalnych rozwiązaniach.

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:

• "Darwin Information Typing Architecture", Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• Post Pawła na LinkedIn: https://www.linkedin.com/feed/update/urn:li:activity:7176518908634439680
• "Content reuse – a productivity booster or a vicious circle?", JetBrains blog: https://blog.jetbrains.com/writerside/2022/08/content-reuse-a-productivity-booster-or-a-vicious-circle/
• "Chunking", OASIS: https://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/chunking.html
• "Definition of DITA maps", OASIS: https://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/definition-of-ditamaps.html
• "Every Page is Page One: Topic-based Writing for Technical Communication and the Web", Mark Baker: http://xmlpress.net/publications/eppo/
• "Topic-based authoring", Wikipedia: https://en.wikipedia.org/wiki/Topic-based_authoring
• "Single-source publishing", Wikipedia: https://en.wikipedia.org/wiki/Single-source_publishing

Wyobraź sobie aplikację bez interfejsu. Ciężko się nie zgodzić, że używanie takiego produktu byłoby trudne. Dlatego istnieją specjaliści tacy jak UX Designer. A teraz wyobraź sobie interfejs bez tekstu. Efekt jest właściwie taki jakby tego interfejsu w ogóle nie było.

Na co dzień nie zwracamy uwagi na to, że aplikacje komunikują się z nami głównie za pomocą tekstu. Dlatego ważne jest, żeby wszelkie opisy pól, przycisków czy komunikaty były napisane w sposób, który efektywnie prowadzi użytkownika do osiągnięcia celu. I tutaj na białym koniu wjeżdza UX Writer. Pewnie mało kto zdaje sobie sprawę z tego, że teksty w interfejsach to osobna dziedzina, która rządzi się swoimi prawami.

Razem z naszym gościem, Wojtkiem Aleksandrem, rozmawiamy m.in. o tym czym jest UX writing, o dobrych praktykach, o tym czego unikać i o wyzwaniach jakie pojawiają się kiedy tworzymy teksty w języku polskim. Ramą dla naszej rozmowy jest wydana niedawno książka Wojtka "UX writing. Moc języka w produktach cyfrowych".

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:

• "User experience, UX", Wikipedia: https://pl.wikipedia.org/wiki/User_experience
• "What is plain language?": https://www.plainlanguage.gov/about/definitions/
• Konferencja soap!: https://soapconf.com/
• "Bad UX Cost Citibank $500M – What Went Wrong?", CMSWire: https://www.cmswire.com/digital-experience/bad-ux-cost-citibank-500m-what-went-wrong/
• "Inbox Zero, czyli porządek w skrzynce pocztowej", Codziennie Produktywnie: https://codziennieproduktywnie.pl/inbox-zero/
• Grammarly: https://www.grammarly.com/
• Wordtune: https://www.wordtune.com/
• Frontitude: https://www.frontitude.com/
• Hemingway Editor: https://hemingwayapp.com/
• Logios Redaktor: https://redaktor.logios.dev/
• "UX writing. Moc języka w produktach cyfrowych" (Helion): https://helion.pl/ksiazki/ux-writing-moc-jezyka-w-produktach-cyfrowych-wojciech-aleksander,uxwri.htm#format/d
• "UX writing. Moc języka w produktach cyfrowych" (Onepress): https://onepress.pl/ksiazki/ux-writing-moc-jezyka-w-produktach-cyfrowych-wojciech-aleksander,uxwri.htm
• Profil Wojtka Aleksandra na LinkedIn: https://www.linkedin.com/in/waleksander/

Wyniki ankiety JetBrains, "The State of Developer Ecosystem 2023", jakie są, każdy widzi. Mało kto używa dity, wszyscy kodują. Ale skąd takie właśnie wyniki i jaką grupę one odzwierciedlają? Czy Tech Writerzy używają narzędzi enterprise? Czy testują dokumentację? Czy wyłania się nam persona Tech Writera, który koduje? Patrzymy na wyniki ankiety krytycznym okiem, badamy czy mogą one sugerować trendy przyszłości i staramy się ocenić kontekst.

Jako bonus bierzemy na warsztat Writerside - narzędzie JetBrains do tworzenia dokumentacji. Omawiamy jego funkcjonalności i fundamentalną zasadę działania. Czy jest to remake MadCap Flare'a? Posłuchaj naszej rozmowy, a dowiesz się co o nim sądzimy.

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:

• "The State of Developer Ecosystem 2023", JetBrains: https://www.jetbrains.com/lp/devecosystem-2023/
• Writerside: https://www.jetbrains.com/writerside/
• "Docs as code", Write the Docs: ⁠https://www.writethedocs.org/guide/docs-as-code/
• Chris Chinchilla: https://chrischinchilla.com/
• MadCap Flare: https://www.madcapsoftware.com/products/flare/
• Adobe RoboHelp: https://www.adobe.com/pl/products/robohelp.html
• ClickHelp: https://clickhelp.com/
• Adobe FrameMaker: https://www.adobe.com/pl/products/framemaker.html
• Help+Manual: https://helpandmanual.com/
• WordPress: https://pl.wordpress.org/
• Drupal: https://www.drupal.org/
• "Markdown", Wikipedia: https://en.wikipedia.org/wiki/Markdown
• Schematron: https://www.schematron.com/
• Swagger UI: https://swagger.io/tools/swagger-ui/
• Redoc: https://github.com/Redocly/redoc
• "Zintegrowane środowisko programistyczne (IDE)", Wikipedia: https://pl.wikipedia.org/wiki/Zintegrowane_%C5%9Brodowisko_programistyczne
• IntelliJ IDEA: https://www.jetbrains.com/idea/
• Wtyczka Writerside: https://plugins.jetbrains.com/plugin/20158-writerside
• "XML schema", Wikipedia: https://en.wikipedia.org/wiki/XML_schema
• "Darwin Information Typing Architecture (DITA)", Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• "DocBook", Wikipedia: https://en.wikipedia.org/wiki/DocBook
• Lightweight DITA: http://docs.oasis-open.org/dita/LwDITA/v1.0/cnprd01/LwDITA-v1.0-cnprd01.html
• "What is vendor lock-in?", TechTarget: https://www.techtarget.com/searchdatacenter/definition/vendor-lock-in

Po długich miesiącach gadania, przyszedł czas na działanie - wreszcie rozpoczęliśmy wdrażanie semantic searcha! Przejście od teorii do praktyki było dość trudne, dlatego mamy dla Was garść informacji, które ułatwią Wam wejście w temat.

Rozmawiamy o tym czym jest semantic search, jakie nam daje korzyści w porównaniu do tradycyjnego wyszukiwania, co musimy mieć, żeby go wdrożyć, jak połączyć ze sobą poszczególne elementy całej układanki i jak takie rozwiązanie zaimplementować.

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:

• "What is semantic search?", Elastic: https://www.elastic.co/what-is/semantic-search
• "Large language model (LLM)", Wikipedia: https://en.wikipedia.org/wiki/Large_language_model
• "What Is Retrieval-Augmented Generation, aka RAG?", NVIDIA Blogs: https://blogs.nvidia.com/blog/what-is-retrieval-augmented-generation/
• "Hybrid Search Explained", Weaviate: https://weaviate.io/blog/hybrid-search-explained
• "Semantic search", SBERT: https://www.sbert.net/examples/applications/semantic-search/README.html#semantic-search
• Hugging Face: https://huggingface.co/
• PyTorch: https://pytorch.org/
• TensorFlow: https://www.tensorflow.org/
• Node.js: https://nodejs.org/en
• Elasticsearch: https://www.elastic.co/elasticsearch
• Kubernetes: https://kubernetes.io/
• "Build Semantic-Search with Elastic search and BERT vector embeddings. ( From scratch )", Abid Saudagar: https://www.youtube.com/watch?v=KSwPR9eig7w
• Jupyter Notebook: https://jupyter.org/
• SentenceTransformers Documentation: https://www.sbert.net/
• "k-nearest neighbor (kNN) search", Elastic Docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html
• Transformers.js, Hugging Face: https://huggingface.co/docs/transformers.js/index
• "Export to ONNX", Hugging Face docs: https://huggingface.co/docs/transformers/serialization
• "Symmetric vs. Asymmetric Semantic Search", SBERT: https://www.sbert.net/examples/applications/semantic-search/README.html#symmetric-vs-asymmetric-semantic-search
• "Tutorial: semantic search with ELSER", Elastic Docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/semantic-search-elser.html
• "The Beginner’s Guide to Text Embeddings", Deepset: https://www.deepset.ai/blog/the-beginners-guide-to-text-embeddings

Każdy zawód w IT zmienia się z biegiem czasu i z rozwojem technologii. Bardzo podobnie jest z technical writingiem. Dawniej pisało się na maszynie, potem na komputerze, a ostatnio pisze się próbki kodu i przykłady zawołań do API. Ale czy jest w zawodzie Tech Writera coś, co się nie zmienia? Czy istnieje zestaw umiejętności, który mimo ewolucji branży pozostaje mniej więcej taki sam?

Rozmawiamy z Tomkiem Prusem na temat najważniejszych cech i umiejętności dobrego Tech Writera. 

Tomek działa w branży od lat i jest managerem doświadczonym w rekrutowaniu Tech Writerów, oraz ogólnie w budowaniu i prowadzeniu zespołów tech writerskich. Poza tym, działa prężnie w ramach MeetContent Wrocław oraz w redakcji techwriter.pl. Jego doświadczenie jest wzbogacone naturalnymi predyspozycjami do motywowania ludzi oraz dużą kreatywnością.

W czasie rozmowy z Tomkiem dotykamy różnic między predyspozycjami i umiejętnościami. Rozmawiamy o tym jak wzmacniać swoje mocne strony i na których umiejętnościach się skupić, żeby móc się łatwo odnaleźć w nowej firmie lub w nowej działce technical writingu.

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:

• International Technical Communication Qualifications Foundation (ITCQF): https://itcqf.org/
• Studia podyplomowe "Komunikacja techniczna", Akademia Finansów
  i Biznesu Vistula: https://vistula.edu.pl/kierunki-studiow/komunikacja-techniczna
• MeetContent: https://meetcontent.org/
• Techwriter.pl: https://techwriter.pl
• Will Robots Take My Job, Technical Writers: https://willrobotstakemyjob.com/technical-writers
• "Dostępność (projektowanie)", Wikipedia: https://pl.wikipedia.org/wiki/Dost%C4%99pno%C5%9B%C4%87_(projektowanie)
• "Architektura informacji", Wikipedia: https://pl.wikipedia.org/wiki/Architektura_informacji
• Information typing: https://docs.oasis-open.org/dita/v1.0/archspec/infotypes.html
• "Darwin Information Typing Architecture", Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• "Użyteczność (informatyka)", Wikipedia: https://pl.wikipedia.org/wiki/U%C5%BCyteczno%C5%9B%C4%87_(informatyka)
• "Component content management system", Wikipedia: https://en.m.wikipedia.org/wiki/Component_content_management_system
• Simplified Technical English (STE): https://www.asd-ste100.org/
• "Readability", Wikipedia: https://en.wikipedia.org/wiki/Readability
• "Information architecture", Wikipedia: https://en.wikipedia.org/wiki/Information_architecture
• "Content strategy", Wikipedia: https://en.wikipedia.org/wiki/Content_strategy
• "Large language model (LLM)", Wikipedia: https://en.wikipedia.org/wiki/Large_language_model
• "Największy wspólny dzielnik", Wikipedia: https://pl.wikipedia.org/wiki/Najwi%C4%99kszy_wsp%C3%B3lny_dzielnik
• "Lint, Lint and Away! Linters for the English Language", Chris Ward: https://dzone.com/articles/lint-lint-and-away-linters-for-the-english-languag

WordPress to zdecydowanie jeden z największych graczy we współczesnym internecie. Ponad 1/3 stron internetowych jest zbudowana właśnie za pomocą tego narzędzia. Strona techwriter.pl była w tym gronie przez ostatnie 10 lat. W tym roku postanowiliśmy przejść na rozwiązanie oparte na platformie gitowej i generatorze stron statycznych.

Rozmawiamy o tym dlaczego zdecydowaliśmy się przejść na Docusaurusa i GitHuba, jak wyglądał proces migracji i czy w ostatecznym rozrachunku była to dobra decyzja, żeby odejść od WordPressa.

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:

• WordPress: https://pl.wordpress.org/
• Docusaurus: https://docusaurus.io/
• GitHub: https://github.com/
• Techwriter.pl: https://techwriter.pl/
• "System zarządzania treścią", Wikipeda: https://pl.wikipedia.org/wiki/System_zarz%C4%85dzania_tre%C5%9Bci%C4%85
• "Usage statistics and market share of WordPress", W3Techs: https://w3techs.com/technologies/details/cm-wordpress
• "Docs as code", Write the Docs: https://www.writethedocs.org/guide/docs-as-code/
• GitHub Pages: https://pages.github.com/
• React: https://react.dev/
• GitHub Issues: https://github.com/features/issues
• MDX: https://mdxjs.com/
• Disqus: https://disqus.com/
• Algolia: https://www.algolia.com/
• GitHub Actions: https://github.com/features/actions
• GitHub Codespaces: https://github.com/features/codespaces
• MeetContent: http://meetcontent.org/

Elastyczne godziny pracy, brak obowiązku przychodzenia do biura i praca z dowolnej lokalizacji to w branży IT od jakiegoś czasu już standard. Wielu z nas bardzo sobie chwali takie rozwiązania i skupia się głównie na ich zaletach, ale rzeczywistość nie jest taka różowa.

Praca w zespole rozproszonym niesie ze sobą wiele wyzwań, takich jak ograniczone możliwości w zakresie dzielenia się wiedzą i współpracy w czasie rzeczywistym oraz wolniejsze rozwiązywanie problemów. Na szczęście nie wszystko stracone. Można wdrożyć pewne rozwiązania, które sprawią, że wydajność wzrośnie, a poziom frustracji zmaleje.

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:

• "#56 Tech Writer robi inżynierię oprogramowania, czyli dobre praktyki prosto od Google", Tech Writer koduje: https://techwriterkoduje.pl/blog/2023/8/1/56
• "Why Meetings Suck and How to Fix Them", WorkLife with Adam Grant: https://open.spotify.com/episode/7qVywKBTNnNmuNTKZKwin0?si=43474d5baa734141
• Jira: https://www.atlassian.com/software/jira
• Bitbucket: https://bitbucket.org/
• No Hello: https://www.nohello.com/
• "Standard DITA (Darwin Information Typing Architecture)", Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• Markdown: https://daringfireball.net/projects/markdown/syntax
• Visual Studio (VS) Code: https://code.visualstudio.com/
• IntelliJ IDEA: https://www.jetbrains.com/idea/
• GitHub: https://github.com/

Prompt Engineer to nowa rola, która pojawiła się w związku z galopującym rozwojem sztucznej inteligencji opartej o large language models (LLM). W dużym skrócie, osoba na tym stanowisku zajmuje się generowaniem zapytań (promptów) dla AI, w taki sposób, żeby były one jak najbardziej optymalne i skuteczne. W pracy Prompt Engineera ważna jest bardzo dobra znajomość języka, wiedza na temat działania algorytmów AI oraz pewien zestaw tzw. kompetencji miękkich.

Wydaje się, że ze względu na swoje umiejętności i doświadczenie, Tech Writer jest dobrym kandydatem na to nowe stanowisko. W naszej rozmowie staramy się ustalić czy takie założenie jest uzasadnione i czy zostanie Prompt Engineerem to potencjalna ścieżka kariery dla technoskryby.

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:

• "Prompt Engineering", Wikipedia: https://en.wikipedia.org/wiki/Prompt_engineering
• "Large language model (LLM)", Wikipedia: https://en.wikipedia.org/wiki/Large_language_model
• Oferta pracy "Prompt Engineer & Librarian": https://www.linkedin.com/jobs/view/3696512483/?eBP=JOB_SEARCH_ORGANIC&refId=4oyL2%2F11R2E5IHbEPcBQig%3D%3D&trackingId=lwW9sbSFJQjRTdjpdk86pQ%3D%3D&trk=flagship3_search_srp_jobs
• "Six skills you need to become an AI prompt engineer", ZDNet: https://www.zdnet.com/article/six-skills-you-need-to-become-an-ai-prompt-engineer/
• "The Hot New Job That Pays Six Figures: AI Prompt Engineering", Forbes: https://www.forbes.com/sites/bernardmarr/2023/05/11/the-hot-new-job-that-pays-six-figures-ai-prompt-engineering/?sh=5996f037d7fa
• Langchain: https://github.com/langchain-ai/langchain
• "Why You Shouldn't Be Writing A New Prompt Every Time", Lance Cummings: https://www.isophist.com/p/why-you-shouldnt-be-writing-a-new
• Profil Lance'a Cummingsa na LinkedIn: https://www.linkedin.com/in/lance-cummings-phd/
• "Prompt Engineering Guide": https://www.promptingguide.ai/

Inżynieria oprogramowania to coś więcej niż programowanie. To tworzenie kodu z myślą o jego utrzymaniu w kontekście czasu, zasobów i skali. Taka szersza perspektywa wymusza na nas stosowanie pewnych zachowań, procesów i narzędzi.

Firma Google stworzyła praktyczny przewodnik opisujący te zagadnienia, który według nas jest wartościową lekturą dla osób pracujących w branży wytwarzania oprogramowania. Rozmawiamy o tym co znajdziecie w książce "Software Engineering at Google", które fragmenty były dla nas najciekawsze i jakie przemyślenia mieliśmy po jej przeczytaniu.

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:

• "Software Engineering at Google", Titus Winters, Tom Manshreck, Hyrum Wright: https://www.oreilly.com/library/view/software-engineering-at/9781492082781/
• Hyrum's Law: https://www.hyrumslaw.com/
• "Bus factor", Wikipedia: https://en.wikipedia.org/wiki/Bus_factor
• "POIT #203: Kariera pokolenia Z w branży IT", Porozmawiajmy o IT: https://porozmawiajmyoit.pl/poit-203-kariera-pokolenia-z-w-branzy-it/
• "Shift-left testing, czyli wczesne testowanie": https://testerzy.pl/baza-wiedzy/shift-left-testing-czyli-wczesne-testowanie
• "Code review", Wikipedia: https://en.wikipedia.org/wiki/Code_review
• "Tech Writer koduje w Pythonie. Przewodnik szybkiego startu", Michał Skowron: https://techwriterkoduje.pl/python/teoria
• "Guard Clause": https://deviq.com/design-patterns/guard-clause

Warto mieć plany i marzenia, szczególnie w kwestii wdrażania usprawnień w swojej pracy. Jako Tech Writerzy często snujemy wizje wykorzystania wspaniałych nowych technologii, które są na topie do przesunięcia naszego procesu tworzenia dokumentacji na wyższy poziom. Często jednak zapominamy o podstawach, bez których takie śmiałe wizje nie mają szansy powodzenia.

Zanim zaczniemy rewolucję, powinniśmy przyjrzeć się temu jak się sprawy mają w naszej organizacji. Tutaj przychodzi nam z pomocą model oceny dojrzałości (maturity model), dzięki któremu dowiemy się na jakim etapie rozwoju jest nasza dokumentacja. Dopiero po zrobieniu takiego "rachunku sumienia" będziemy mogli wykonać kolejny krok w postaci planowania usprawnień.

Rozmawiamy o przykładowym maturity modelu dla dokumentacji, zastanawiamy się co można zrobić, żeby przejść na wyższe poziomy, subiektywnie oceniamy innych i teoretyzujemy na temat przyszłości.

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:

• Konferencja soap!: https://soapconf.com/
• Etteplan: https://www.etteplan.com/pl
• "Maturity model", Wikipedia: https://en.wikipedia.org/wiki/Maturity_model
• "What is ContentOps", Heretto: https://heretto.com/blog/what-is-contentops/
• "Content strategy", Wikipedia: https://en.wikipedia.org/wiki/Content_strategy
• "Generative artificial intelligence", Wikipedia: https://en.wikipedia.org/wiki/Generative_artificial_intelligence
• "Help authoring tool (HAT)", Wikipedia: https://en.wikipedia.org/wiki/Help_authoring_tool
• "Darwin Information Typing Architecture (DITA)", Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• "Component Content Management System (CCMS)", Wikipedia: https://en.m.wikipedia.org/wiki/Component_content_management_system
• "About pull requests", GitHub : https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
• "Docs as Code", Write the Docs: https://www.writethedocs.org/guide/docs-as-code/
• "Lint (software)", Wikipedia: https://en.wikipedia.org/wiki/Lint_(software)
• GitHub Copilot: https://github.com/features/copilot
• "Style guide", Wikipedia: https://en.wikipedia.org/wiki/Style_guide
• Acrolinx: https://www.acrolinx.com/
• Schematron: https://www.schematron.com/
• Oxygen XML: https://www.oxygenxml.com/
• Visual Studio Code (VS Code): https://code.visualstudio.com/
• Jenkins: https://www.jenkins.io/
• "Microcontent", Wikipedia: https://en.wikipedia.org/wiki/Microcontent
• "What is "Intelligent Content"?, Storyblok: https://www.storyblok.com/mp/intelligent-content
• Docusaurus: https://docusaurus.io/
• "Large language model (LLM)", Wikipedia: https://en.wikipedia.org/wiki/Large_language_model
• "The economic potential of generative AI: The next productivity frontier", McKinsey Digital: https://www.mckinsey.com/capabilities/mckinsey-digital/our-insights/the-economic-potential-of-generative-ai-the-next-productivity-frontier#introduction

Technoskryby nie gęsi, iż swoje przemyślenia na temat AI mają.

O sztucznej inteligencji jest wszędzie głośno, nie tylko w branżach związanych bezpośrednio z technologią. O co to całe zamieszanie?

Rozmawiamy o tym czym są a czym nie są duże modele językowe (large language models), co potrafią i jak można w praktyczny sposób wykorzystać w komunikacji technicznej oparte na nich rozwiązania, takie jak Bing Chat i GitHub Copilot. Poza przyziemnymi przykładami, pozwalamy sobie również na odrobinę fantazji.

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:

• "Don't panic! How to ride the wave of AI in technical communication and not drown", Tech Writer koduje: https://techwriterkoduje.pl/read
• "#32 Tech Writer zatrudnia asystenta, czyli sztuczna inteligencja w służbie dokumentacji", Tech Writer koduje: https://techwriterkoduje.pl/blog/2021/7/29/32
• "Large language model (LLM)", Wikipedia: https://en.wikipedia.org/wiki/Large_language_model
• "Generative artificial intelligence", Wikipedia: https://en.wikipedia.org/wiki/Generative_artificial_intelligence
• Bing Chat: https://www.microsoft.com/en-us/edge/features/bing-chat?form=MT00D8&ch
• ChatGPT: https://openai.com/product/chatgpt
• "Microsoft opens Bing AI for public testing, no waitlist required", Engadget: https://www.engadget.com/microsoft-opens-bing-ai-public-testing-no-waitlist-070024329.html
• "Microsoft confirms Bing runs on the new GPT-4 model", Engadget: https://www.engadget.com/microsoft-confirms-bing-runs-on-the-new-gpt-4-model-184121316.html
• GitHub Copilot: https://github.com/features/copilot
• Visual Studio Code (VS Code): https://code.visualstudio.com/
• Amazon CodeWhisperer: https://aws.amazon.com/codewhisperer/
• IntelliJ IDEA: https://www.jetbrains.com/idea/
• "Is ChatGPT Going To Take My Technical Writing Job?", Coffee and Content: https://www.brighttalk.com/webcast/9273/577257
• "Darwin Information Typing Architecture (DITA)", Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• "Semantic search", Towards Data Science: https://towardsdatascience.com/semantic-search-73fa1177548f
• Auto-GPT: https://autogpt.net/

Dokumentacja nie powstaje w próżni, tylko jako część większego procesu tworzenia oprogramowania lub innego produktu. Dlatego cały cykl tworzenia dokumentacji to wielkie nieskończone koło, w którym biorą udział zespoły projektowe, produktowe, testerskie i dokumentacyjne.

I tutaj na scenę wchodzi ContentOps!

Tak jak DevOps, ContentOps to sposób na ciągłe dostarczanie (continuous delivery) i ciągłe usprawnianie (continuous improvement) dokumentacji. W tym odcinku rozmawiamy o tym jakie są kluczowe elementy tego cyklu, jakie role biorą w nim udział i jaki to ma wpływ na poszczególnych uczestników. Jeżeli interesuje Cię strategia tworzenia treści, architektura informacji, proces pisania i narzędzia, to na pewno znajdziesz tu coś dla siebie.

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:

• Konferencja soap!: https://soapconf.com/
• "#3 SVG - przenieś grafikę w dokumentacji na wyższy poziom", Tech Writer koduje: https://techwriterkoduje.pl/blog/2019/6/14/3
• "#27 Tech Writer szkoli się z Pythona", Tech Writer koduje: https://techwriterkoduje.pl/blog/2021/2/17/27
• "#42 Konferencja soap! 2022 - podsumowanie", Tech Writer koduje: https://techwriterkoduje.pl/blog/2022/6/14/42
• "What is DevOps?", Amazon: https://aws.amazon.com/devops/what-is-devops/
• "What is ContentOps", Heretto: https://heretto.com/blog/what-is-contentops/
• "Understanding content operations - Definitions and resources", GatherContent: https://gathercontent.com/blog/understanding-contentops-definitions-and-resources
• "Information architecture", Wikipedia: https://en.wikipedia.org/wiki/Information_architecture
• "Content strategy", Wikipedia: https://en.wikipedia.org/wiki/Content_strategy
• "#52 Od przybytku głowa też boli, czyli Tech Writer próbuje utrzymać dokumentację w ryzach", Tech Writer koduje: https://techwriterkoduje.pl/blog/2023/4/11/52
• "Docs as Code", Write the Docs: https://www.writethedocs.org/guide/docs-as-code/
• "Darwin Information Typing Architecture (DITA)", Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• "Component Content Management System (CCMS)", Wikipedia: https://en.m.wikipedia.org/wiki/Component_content_management_system
• "About pull requests", GitHub : https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests

Dokumentacji powinno być tyle ile trzeba, nie więcej, nie mniej.

Nasi goście z firmy Etteplan, Barbara Kardel-Piątkowska i Grzegorz Nowak, na co dzień starają się utrzymać racjonalny poziom ilości dokumentacji i stworzyć rozsądne środowisko pracy nad nią. Kluczem do sukcesu są właściwe planowanie, odpowiednie procedury i narzędzia. Dodatkowego smaczku dodaje jeszcze fakt, że Basia i Grzesiek tworzą dokumentację do maszyn, która rządzi się innymi prawami niż dokumentacja do oprogramowania.

Rozmawiamy o reusie, conditionalach, zarządzaniu treścią i innych ciekawych rzeczach, które mogą być pomocne w opanowaniu zbyt dużej ilości dokumentacji.

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:

• Etteplan: https://www.etteplan.com/
• Dyrektywa maszynowa: https://www.ce-polska.pl/dyrektywa-2006-42-we?gclid=EAIaIQobChMIvYD5qOj8_QIVlgCiAx1MdwpwEAAYASAAEgI9efD_BwE
• Simplified Technical English (STE): https://www.asd-ste100.org/
• Git: https://git-scm.com/
• Subversion: https://subversion.apache.org/
• Component Content Management System (CCMS), Wikipedia: https://en.m.wikipedia.org/wiki/Component_content_management_system
• Information architecture (IA), Wikipedia: https://en.wikipedia.org/wiki/Information_architecture
• "Content reuse – a productivity booster or a vicious circle?", JetBrains blog: https://blog.jetbrains.com/writerside/2022/08/content-reuse-a-productivity-booster-or-a-vicious-circle/
• Profil Basi na LinkedIn: https://www.linkedin.com/in/barbara-kardel-piatkowska/
• Profil Grześka na LinkedIn: https://www.linkedin.com/in/nowakgp/

Jakiś czas temu Docusaurus zaskarbił sobie naszą sympatię, dlatego strona naszego podcastu przez kilka lat opierała się właśnie na tym narzędziu. Nadszedł moment, w którym postanowiliśmy ją odświeżyć. Przy tej okazji rozstaliśmy się z naszym starym znajomym i sięgnęliśmy po Next.js.

Rozmawiamy o tym dlaczego zdecydowaliśmy się na migrację, co dzięki temu zyskaliśmy i w jaki sposób nowe narzędzie pozwoliło nam rozwiązać pewne problemy i wprowadzić usprawnienia.

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:

• Next.js: https://nextjs.org/
• Docusaurus: https://docusaurus.io/
• Anchor.fm: https://anchor.fm
• GitHub Pages: https://pages.github.com/
• GitHub Actions: https://github.com/features/actions
• Material UI (MUI): https://mui.com/
• React: https://pl.reactjs.org/
• Express: https://expressjs.com/
• Node.js: https://nodejs.org/
• EJS: https://ejs.co/
• Element : https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio
• Zasada Pareta: https://pl.wikipedia.org/wiki/Zasada_Pareta
• Gra siatka koncentracji: https://techwriterkoduje.pl/focusgrid
• Algolia: https://www.algolia.com/
• Fuse.js: https://fusejs.io/
• Źródło strony techwriterkoduje.pl na GitHub: https://github.com/techwriterkoduje/podcast-site
• Incremental Static Regeneration (ISR) w Next.js: https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration
• "#50 Tech Writer bloguje z GitHub Issues, czyli nietuzinkowy sposób na platformę contentową", Tech Writer koduje: https://techwriterkoduje.pl/blog/2023/1/26/50

Kiedy słyszymy Content Management System (CMS) to najpewniej w pierwszym momencie przychodzi nam na myśl WordPress albo Drupal. Raczej mało kto podejrzewa, że System Zarządzania Incydentami (Issue Tracking System) może również w powodzeniem służyć nam do zarządzania treścią.

Rozmawiamy o platformie Octotype, która wykorzystuje Next.js do publikowania wpisów z GitHub Issues. Omawiamy szczegóły tego rozwiązania i zastanawiamy się czy podobne podejście można by wykorzystać w świecie dokumentacji technicznej.

Sprostowanie: Podczas nagrania skrótowiec ISR rozwijamy jako "Incremental Site Regeneration". To jest błąd z naszej strony, ponieważ prawidłowa wersja to "Incremental Static Regeneration".

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:

• Octotype: https://octotype.app/
• Profil Pablo Bermejo na LinkedIn: https://es.linkedin.com/in/pablobermejo
• Vercel: https://vercel.com
• Medium: https://medium.com/
• Dev.to: https://dev.to/
• Hashnode: https://hashnode.com/
• GitHub Issues: https://github.com/features/issues
• ChatGPT: https://openai.com/blog/chatgpt/
• TypeScript: https://www.typescriptlang.org/
• Incremental Static Regeneration (ISR) w Next.js: https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration
• Introducing JSX: https://reactjs.org/docs/introducing-jsx.html
• "#32 Tech Writer zatrudnia asystenta, czyli sztuczna inteligencja w służbie dokumentacji", Tech Writer koduje: https://techwriterkoduje.pl/blog/2021/07/29/tech-writer-zatrudnia-asystenta
• Mastodon: https://joinmastodon.org/
• diaspora*: https://diasporafoundation.org/
• WordPress: https://wordpress.com/
• Strapi: https://strapi.io/

Indeks czytelności (z ang. "readability index") to wskaźnik mówiący nam jak trudny do przeczytania jest dany tekst. Istnieje kilka odmian tego wskaźnika, np. Flesch-Kincaid czy SMOG. 

Tech Writer, UX Designer i każda inna osoba zajmująca się tworzeniem treści powinna mieć na uwadze indeks czytelności i dbać o to, żeby był on dostosowany do odbiorcy. Na rynku istnieje kilka narzędzi, które mogą nam w tym pomóc. Niedawno mieliśmy okazję sprawdzić niektóre z nich i w tym odcinku dzielimy się wnioskami i spostrzeżeniami z naszych testów.

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:

• Readability, Wikipedia: https://en.wikipedia.org/wiki/Readability 
• Dostępność (projektowanie), Wikipedia: https://pl.wikipedia.org/wiki/Dost%C4%99pno%C5%9B%C4%87_(projektowanie)
• Readability indices: https://www.analyzemywriting.com/readability_indices.html
• "Flesch Reading Ease and the Flesch Kincaid Grade Level", Readable: https://readable.com/readability/flesch-reading-ease-flesch-kincaid-grade-level/
• Jasnopis: https://www.jasnopis.pl/
• Logios: https://logios.dev/
• Acrolinx: https://www.acrolinx.com/
• Hemingway: https://hemingwayapp.com/
• Textstat: https://pypi.org/project/textstat/
• Vale: https://vale.sh/
• Oxygen XML Author: https://www.oxygenxml.com/xml_author.html
• Figma: https://www.figma.com/
• Alex.js: https://github.com/get-alex/alex
• Visual Studio (VS) Code: https://code.visualstudio.com/
• IntelliJ IDEA: https://www.jetbrains.com/idea/
• MDX: https://mdxjs.com/
• Wprowadzenie do JSX: https://pl.reactjs.org/docs/introducing-jsx.html

Na pierwszy rzut oka pisanie dokumentacji ma niewiele wspólnego z frontend developmentem. Kiedy jednak spojrzymy na nowoczesną dokumentację do oprogramowania to możemy odnieść wrażenie, że tak naprawdę niewiele różni się ona od zwykłej strony internetowej. Czy to oznacza, że nadszedł czas, żeby zostać Frontend Tech Writerem?

Rozmawiamy o tym jakie umiejętności z zakresu technologii webowych mogą się przydać w pracy technoskryby, w jaki sposób je zdobywać i do czego można je wykorzystać w procesie tworzenia dokumentacji.

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:

• "Co to jest Front-end i kim jest frontend developer?", Software Development Academy: https://sdacademy.pl/frontend-co-to-jest/ 
• HTML: https://pl.wikipedia.org/wiki/HTML
• CSS: https://pl.wikipedia.org/wiki/Kaskadowe_arkusze_styl%C3%B3w
• WordPress: https://wordpress.com/
• JavaScript: https://pl.wikipedia.org/wiki/JavaScript
• "#47 Tech Writer zgłębia tajniki dostępności cyfrowej, czyli jak tworzyć dokumentację dla wszystkich", Tech Writer koduje: https://techwriterkoduje.pl/blog/2022/10/13/dostepnosc-cyfrowa
• "#25 Tech Writer koduje w dokumentacji, czyli Markdown w wersji rozszerzonej", Tech Writer koduje: https://techwriterkoduje.pl/blog/2021/01/21/tech-writer-koduje-w-dokumentacji
• Markdown: https://daringfireball.net/projects/markdown/syntax
• MDX: https://mdxjs.com/
• "Wprowadzenie do JSX": https://pl.reactjs.org/docs/introducing-jsx.html
• React: https://pl.reactjs.org/
• "What is a Static Site Generator? And 3 ways to find the best one": https://www.netlify.com/blog/2020/04/14/what-is-a-static-site-generator-and-3-ways-to-find-the-best-one/
• Docusaurus: https://docusaurus.io/
• Jamstack: https://jamstack.org/
• EJS: https://ejs.co/
• Eleventy (11ty): https://www.11ty.dev/
• TypeScript: https://www.typescriptlang.org/
• Standard DITA (Darwin Information Typing Architecture): https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• MadCap Flare: https://www.madcapsoftware.com/products/flare/
• Git: https://git-scm.com/

W dzisiejszych czasach, stworzenie strony internetowej jest dość łatwe i szybkie. Jednak stworzenie strony internetowej, która spełnia wymogi dostępności cyfrowej to zupełnie inna bajka. Tutaj potrzebna jest już odpowiednia wiedza, umiejętności oraz znajomość przepisów.

Dlatego zaprosiliśmy Dawida Górnego, Kacpra Mikockiego i Tomasza Boniora z firmy Accens, żeby opowiedzieli nam o tym czym jest dostępność, jak o nią zadbać, jak ją testować, jakie narzędzia mogą nam pomóc w wykrywaniu potencjalnych problemów i w jaki sposób technokrybowie mogą sprawić, że ich dokumentacja będzie przyjazna dla każdego.

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:

• Accens: https://accens.io/
• Dostępność (projektowanie), Wikipedia: https://pl.wikipedia.org/wiki/Dost%C4%99pno%C5%9B%C4%87_(projektowanie) 
• "Czym jest dostępność cyfrowa? Na czym polega?", Accens: https://accens.io/blog/pl/dostepnosc-cyfrowa-definicja/
• Używalność (informatyka), Wikipedia: https://pl.wikipedia.org/wiki/U%C5%BCyteczno%C5%9B%C4%87_(informatyka)
• Americans with Disabilities Act of 1990, Wikipedia: https://en.wikipedia.org/wiki/Americans_with_Disabilities_Act_of_1990
• Konwencja o prawach osób niepełnosprawnych, Ministerstwo Rodziny i Polityki Społecznej: https://www.gov.pl/web/rodzina/konwencja-o-prawach-osob-niepelnosprawnych
• Web Content Accessibility Guidelines (WCAG), W3C: https://www.w3.org/TR/WCAG21/
• IBM Equal Access Toolkit: https://www.ibm.com/able/toolkit/tools
• Axe DevTools: https://www.deque.com/axe/devtools/
• Material UI: https://mui.com/
• TypeScript: https://www.typescriptlang.org/

Trzy dni, pięć lokalizacji w różnych częściach Europy i jeden cel -  stworzenie produktów technologicznych, które pozwolą na rozwiązanie  problemów związanych z wojną. "Hack for Peace" to wydarzenie dla wszystkich, którzy pracują z technologią i chcieliby wykorzystać swoje umiejętności dla wspólnego dobra.

Na koniec, jury składające się z przedstawicieli organizatorów i partnerów wybierze trzech zwycięzców, którzy będą mieli możliwość rozwijania swoich pomysłów pod opieką mentorów. Przewidziane są również nagrody pieniężne od "House of Europe".

Posłuchajcie naszej krótkiej rozmowy z Olgą Sulik z firmy Sigma Software, w której staramy się Wam przybliżyć tę zacną ideę.

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:

• Sigma Software: https://sigma.software/
• "Hack for Peace": https://hackforpeace.net/
• Informacja prasowa o "Hack for Peace": https://docs.google.com/document/d/1-brngt30XlNYUTnfhfMPe3QVp1ZF5U-A/edit 
• Femmegineering Meetup w Krakowie: https://www.eventbrite.co.uk/e/femmegineering-meetup-in-search-of-the-eternal-code-tickets-415343793467?aff=ebdsoporgprofile

Open source oznacza, że się nie płaci, prawda? Niezupełnie. Nie płaci się pieniędzmi, ale za to płaci się swoim czasem. Trzeba mieć też trochę umiejętności, żeby to ogarnąć. Dlatego może lepiej zapłacić za rozwiązanie enterprise i mieć problem z głowy. Tylko wtedy też musimy zainwestować swój czas w utrzymanie systemu, nie mówiąc już o negocjacjach z vendorem i innych trudnościach.

Rozmawiamy o plusach i minusach rozwiązań open source i enterprise w technical writingu. Jak podejść do wyliczania kosztów? W jakich sytuacjach lepiej zdać się na vendora, a w jakich lepiej polegać na sobie. Jakie są "ukryte" koszty obu ścieżek? Jeśli stoisz przed wyborem tech stacka dla technical writingu, ten odcinek jest dla Ciebie.

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:

• WordPress: https://wordpress.com/
• Docusaurus: https://docusaurus.io/
• Next.js: https://nextjs.org/
• Component Content Management System (CCMS): https://en.m.wikipedia.org/wiki/Component_content_management_system
• MadCap Flare: https://www.madcapsoftware.com/products/flare/#content
• Adobe RoboHelp: https://www.adobe.com/products/robohelp.html
• Snyk Advisor: https://snyk.io/advisor/
• "How one developer just broke Node, Babel and thousands of projects in 11 lines of JavaScript", The Register: https://www.theregister.com/2016/03/23/npm_left_pad_chaos/
• "Open Source Developer Sabotages npm Libraries ‘Colors,’ ‘Faker’", FOSSA: https://fossa.com/blog/npm-packages-colors-faker-corrupted/
• Stack Overflow: https://stackoverflow.com/
• Skeumorfizm: https://pl.wikipedia.org/wiki/Skeumorfizm

Rekrutacja to temat zawsze na czasie. Również wśród technoskrybów wzbudza on wiele emocji. Dlatego po ponad 2-letniej przerwie wracamy do niego razem z Michałem Słapakiem (Motorola Solutions) i Tomkiem Prusem (Atlassian).

Przyglądamy się obecnej sytuacji na rynku pracy dla Tech Writerów w Polsce oraz procesowi rekrutacyjnemu zarówno pod kątem poziomu umiejętności aplikujących jak i oczekiwań zatrudniających. Oceniamy jak zmieniły się realia w ostatnich latach, staramy się zbudować profil kandydata, który posiada zestaw najbardziej poszukiwanych umiejętności i zastanawiamy jak trudno jest wejść w tech writing w branży IT osobom z zewnątrz.

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:

• "#12 Tech Writer się rekrutuje, czyli jak ważne są umiejętności techniczne", Tech Writer koduje: https://techwriterkoduje.pl/blog/2020/01/20/tech-writer-sie-rekrutuje
• Motorola Solutions: https://www.motorolasolutions.com/en_xu.html
• Unit4: https://www.unit4.com/
• Atlassian: https://www.atlassian.com/
• Guidewire Software: https://www.guidewire.com/
• International Technical Communication Qualification Foundation (ITCQF): https://itcqf.org/
• Komunikacja Techniczna - studia podyplomowe (Vistula): https://www.vistula.edu.pl/kierunki-studiow/kontynuacja-edukacji/studia-podyplomowe/informatyka/komunikacja-techniczna
• Python: https://www.python.org/
• Standard DITA (Darwin Information Typing Architecture): https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• Raport "Technical writing in Central and Eastern Europe": https://itcqf.org/wp-content/uploads/2022/05/Technical-Writing-in-Central-and-Eastern-Europe.pdf
• Profil Michała Słapaka na LinkedIn: https://www.linkedin.com/in/michal-slapak-a1a2012/
• Profil Tomasza Prusa na LinkedIn: https://www.linkedin.com/in/tomasz-prus-4b09b01a/

Zbudowanie strony z dokumentacją od zera może się wydawać nie lada wyzwaniem. Istnieje mnóstwo sposobów na podejście do tematu. Kiedy myślimy nad potencjalnym rozwiązaniem, do głowy przychodzą nam następujące pytania:

Czy można do tego celu użyć darmowych narzędzi? Czy istnieje coś takiego jak bezpłatny hosting? Jak pisać dokumentację bez CCMSa? Jak wygenerować PDFy bez użycia standardu DITA?

W tym odcinku staramy się stworzyć prosty (i bardzo subiektywny) przepis, który pomoże Wam zbudować nowoczesną stronę z dokumentacją w relatywnie krótkim czasie.

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:

• "#38 Tech Writer walczy z hakerami, czyli jak zadbać o bezpieczeństwo dokumentacji", Tech Writer koduje: https://techwriterkoduje.pl/blog/2022/01/10/tech-writer-walczy-z-hakerami
• Static Site Generator: https://www.gatsbyjs.com/docs/glossary/static-site-generator/
• Docusaurus: https://docusaurus.io/
• Algolia: https://www.algolia.com/
• Markdown: https://daringfireball.net/projects/markdown/syntax
• Visual Studio (VS) Code: https://code.visualstudio.com/
• VSCodium: https://vscodium.com/
• Rozszerzenie Vale dla VS Code: https://github.com/errata-ai/vale-vscode
• Git: https://git-scm.com/
• GitHub: https://github.com/
• GitHub Pages: https://pages.github.com/
• GitHub Actions: https://github.com/features/actions
• Repozytorium dla strony Tech Writer koduje: https://github.com/techwriterkoduje/site-source
• TeamCity: https://www.jetbrains.com/teamcity/
• Jenkins: https://www.jenkins.io/
• Kubernetes: https://kubernetes.io/
• Docker: https://www.docker.com/
• DITA Open Toolkit (OT): https://www.dita-ot.org/
• Oxygen XML: https://www.oxygenxml.com/
• mr-pdf: https://www.npmjs.com/package/mr-pdf

Konferencja soap! to święto każdego Tech Writera. Razem z Edytą Rakowską, technoskrybką z Wrocławia, omawiamy nasze ulubione warsztaty i wystąpienia z edycji 2022. 

Rozmawiamy o sztucznej inteligencji, planowaniu ContentOps, umiejętnościach, które pozwolą nam przetrwać czwartą rewolucję przemysłową i narzędziach. Łączymy ze sobą niepowiązane tematy, odkrywamy nowe dziedziny do zbadania i nie stronimy od rożnej jakości żartów. 

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:

• Konferencja soap!: https://soapconf.com/
• "Event-driven vs REST API interactions": https://blog.axway.com/amplify-products/api-management/event-driven-vs-rest-api-interactions
• AsyncAPI: https://www.asyncapi.com/
• Application programming interface (API): https://pl.wikipedia.org/wiki/Interfejs_programowania_aplikacji
• OpenAI: https://openai.com/
• "#32 Tech Writer zatrudnia asystenta, czyli sztuczna inteligencja w służbie dokumentacji", Tech Writer koduje: https://techwriterkoduje.pl/blog/2021/07/29/tech-writer-zatrudnia-asystenta
• DALL-E 2: https://openai.com/dall-e-2/
• OBS (Open Broadcaster Software): https://obsproject.com/
• Restream: https://restream.io/
• "What Is ContentOps?": https://heretto.com/what-is-contentops/
• "These are the top 10 job skills of tomorrow – and how long it takes to learn them": https://www.weforum.org/agenda/2020/10/top-10-work-skills-of-tomorrow-how-long-it-takes-to-learn-them/

"Docs like code" czy "Docs as code" to model tworzenia dokumentacji, którego głównym założeniem jest traktowanie dokumentacji jak kodu pod kątem procesów oraz narzędzi, których używamy do jej tworzenia. Jednak czy można pójść o krok dalej i rozszerzyć założenia tego modelu na sam proces pisania dokumentacji?

Rozmawiamy o tym czy pisanie dokumentacji i kodowanie są do siebie podobne, czy kodujący Tech Writer ma jakieś dodatkowe umiejętności, dzięki którym jest w stanie dostarczać dokumentację lepszej jakości i czy dokumentacja mogłaby czerpać korzyści z testów, które są tworzone dla 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 like code", Anne Gentle:  https://www.docslikecode.com/book/
• "Docs as code", Write the Docs:  https://www.writethedocs.org/guide/docs-as-code/
• "#39 DITA as code, czyli klasyczny standard w nowoczesnym wydaniu", Tech Writer koduje: https://techwriterkoduje.pl/blog/2022/02/14/dita-as-code
• Standard DITA (Darwin Information Typing Architecture): https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• Oxygen XML: https://www.oxygenxml.com/#bidx-xml-author
• IntelliJ IDEA: https://www.jetbrains.com/idea/
• Microsoft Word: https://www.microsoft.com/pl-pl/microsoft-365/word
• "Programowanie imperatywne oraz deklaratywne", Codenga: https://codenga.pl/artykuly/poradniki/programowanie-imperatywne-oraz-deklaratywne
• React: https://pl.reactjs.org/
• Programowanie obiektowe: https://pl.wikipedia.org/wiki/Programowanie_obiektowe
• Docusaurus: https://docusaurus.io/
• Behavior-driven development (BDD): https://pl.wikipedia.org/wiki/Behavior-driven_development
• Cucumber: https://cucumber.io/
• "Rodzaje testów oprogramowania", Testerzy.pl: https://testerzy.pl/baza-wiedzy/artykuly/rodzaje-testow-oprogramowania
• Test-driven development (TDD): https://pl.wikipedia.org/wiki/Test-driven_development
• Foobar: https://pl.wikipedia.org/wiki/Foobar
• Nuxt: https://nuxtjs.org/

Jedni marzą o drogim samochodzie a drudzy o ekskluzywnych wakacjach w ciepłych krajach. A o czym marzą Tech Writerzy?

Odpowiedź znaleźliśmy w newsletterze "Write the Docs" z marca 2022. Okazuje się, że technoskrybowie marzą o tym, żeby pewne elementy ich pracy były zautomatyzowane. Jest to temat bliski naszemu sercu, dlatego postanowiliśmy zmierzyć się z listą życzeń z newslettera. Bazując na swoim doświadczeniu oraz zdobytych informacjach, staramy się zaproponować praktyczne rozwiązania, które przybliżą nasze koleżanki i kolegów po fachu do wymarzonej automatyzacji.

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:

• Newsletter "Write the Docs", marzec 2022: https://www.writethedocs.org/blog/newsletter-march-2022/
• TestCafe: https://testcafe.io/
• ImageMagick: https://imagemagick.org/index.php
• "Simplified User Interface: The Beginner’s Guide": https://www.techsmith.com/blog/simplified-user-interface/
• Screen Capture API: https://developer.mozilla.org/en-US/docs/Web/API/Screen_Capture_API
• "Sharing Screens with the New Javascript Screen Capture API": https://fjolt.com/article/javascript-screen-capture-api
• Biblioteka Pillow: https://pillow.readthedocs.io/en/stable/
• Selenium WebDriver: https://www.selenium.dev/documentation/webdriver/
• Conventional commits: https://www.conventionalcommits.org
• Vale: https://github.com/errata-ai/vale
• "Documentation as code: Part 3: A Linting How To - The Vale Linter in action (Demo)", Tag1: https://www.tag1consulting.com/blog/documentation-code-linting-part3
• "Documentation testing", GitLab: https://docs.gitlab.com/14.8/ee/development/documentation/testing.html
• Alex: https://alexjs.com/
• LanguageTool: https://languagetool.org/pl
• Schematron: https://www.schematron.com/
• "Creative writing with GitHub copilot", Chris Ward: https://www.youtube.com/watch?v=V_CmYyvaMqE
• "Lint, Lint and Away! Linters for the English Language", Chris Ward: https://dzone.com/articles/lint-lint-and-away-linters-for-the-english-languag
• Code Spell Checker: https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker
• Gremlins Checker: https://marketplace.visualstudio.com/items?itemName=nhoizey.gremlins
• "Meet Grazie: the ultimate spelling, grammar, and style checker for IntelliJ IDEA", IntelliJ: https://blog.jetbrains.com/idea/2019/11/meet-grazie-the-ultimate-spelling-grammar-and-style-checker-for-intellij-idea/
• Pandoc: https://pandoc.org/
• "DITA as code - a modern approach to the classic standard", Tech Writer koduje: https://techwriterkoduje.pl/dita-as-code
• AutoIt: https://www.autoitscript.com/site/
• Bitnami: https://github.com/bitnami

DITA w modelu "docs as code"? Kto to widział? Czy to się da zrobić i czy to w ogóle ma sens? Po snuciu teorii na ten temat, przyszedł czas na konkretne działania.

Rozmawiamy o tym co do tej pory udało nam się zrobić, żeby w naszej organizacji wdrożyć "DITA as code". Mówimy o narzędziach, przykładowym procesie robienia zmian w dokumentacji, napotkanych trudnościach i kolejnych krokach.

Jeśli "DITA z gita" jest bliska Waszemu sercu to zapraszamy do odsłuchu.

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:

• "#16 DITA z Gita", Tech Writer koduje: https://techwriterkoduje.pl/blog/2020/04/22/dita-z-gita
• "#8 DITA OT - static site generator dla wtajemniczonych", Tech Writer koduje: https://techwriterkoduje.pl/blog/2019/09/28/dita-ot
• Standard DITA (Darwin Information Typing Architecture): https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
• Component Content Management System (CCMS): https://en.m.wikipedia.org/wiki/Component_content_management_system
• Git: https://git-scm.com/
• "Docs as code", Write the Docs: https://www.writethedocs.org/guide/docs-as-code/
• Bitbucket: https://bitbucket.org/
• Git submodules: https://www.atlassian.com/git/tutorials/git-submodule
• Bitbucket pull requests: https://www.atlassian.com/git/tutorials/making-a-pull-request
• Oxygen XML: https://www.oxygenxml.com/#bidx-xml-author
• "Krytyczna podatność w bibliotece Apache Log4j": https://cert.pl/posts/2021/12/krytyczna-podatnosc-w-bibliotece-apache-log4j/
• Sourcetree: https://www.sourcetreeapp.com/
• DITA Open Toolkit (DITA OT): https://www.dita-ot.org/
• Docker: https://www.docker.com/
• Amazon Simple Storage Service (S3): https://aws.amazon.com/s3/
• TeamCity: https://www.jetbrains.com/teamcity
• Schematron: https://www.schematron.com/
• "Content Reuse": https://paligo.net/docs/en/content-reuse.html
• Git hooks: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks
• "Readability – what is it and how do I improve it?", Paweł Kowaluk (soap! 2018): https://www.youtube.com/watch?v=LzrHrIOHhz8

Stare porzekadło "Tańcz jakby nikt nie patrzył" niestety nie sprawdzi się w kontekście dokumentacji. Tech Writer powinien raczej stosować zasadę "Szyfruj wszystko tak jakby cały świat chciał przeczytać to co masz do ukrycia". Z Mateuszem Olejarką, specjalistą w zakresie bezpieczeństwa aplikacji webowych, rozmawiamy o tym na co powinniśmy zwracać uwagę w procesie tworzenia dokumentacji, żeby była ona bezpieczna. Dowiecie się gdzie czyhają potencjalne zagrożenia i jak sobie z nimi radzić.

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:

• Amazon S3: https://aws.amazon.com/s3/
• "README.md, czyli historia zbyt pomocnego pliku", Techwriter.pl: http://techwriter.pl/readme-md-czyli-historia-zbyt-pomocnego-pliku/
• SmartDeblur: http://smartdeblur.net/
• Fake Name Generator: https://www.fakenamegenerator.com/
• DumpsterDiver: https://github.com/securing/DumpsterDiver
• MD5: https://pl.wikipedia.org/wiki/MD5
• "Security agencies leak sensitive data by failing to sanitize PDF files": https://therecord.media/security-agencies-leak-sensitive-data-by-failing-to-sanitize-pdf-files/
• FOCA (Fingerprinting Organizations with Collected Archives): https://github.com/ElevenPaths/FOCA
• "FBI used Instagram, an Etsy review, and LinkedIn to identify a protestor accused of arson": https://www.theverge.com/2020/6/18/21295301/philadelphia-protester-arson-identified-social-media-etsy-instagram-linkedin
• "What is typosquatting and how typosquatting attacks are responsible for malicious modules in npm": https://snyk.io/blog/typosquatting-attacks/
• Cross Site Scripting (XSS): https://owasp.org/www-community/attacks/xss/
• Wayback Machine: https://web.archive.org/
• Okta: https://www.okta.com/
• Single Page Application (SPA): https://pl.wikipedia.org/wiki/Single_Page_Application
• JSON Web Token (JWT): https://jwt.io/
• Non-disclosure agreement (NDA): https://en.wikipedia.org/wiki/Non-disclosure_agreement
• Kevin Mitnick: https://en.wikipedia.org/wiki/Kevin_Mitnick
• Profil Mateusza Olejarki na LinkedIn: https://pl.linkedin.com/in/molejarka