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/