Tech Writer koduje

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

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