Tech Writer koduje

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.

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.

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.

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 <audio>: 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