Skip to main content
Tech Writer koduje

Tech Writer koduje

By Doc Developer

Podcast o technicznej stronie tworzenia dokumentacji w IT. Skupiamy się na tym jak Tech Writer może wpasować się w środowisko programistów zarówno pod kątem sposobu pracy jak i używanych technologii, narzędzi i rozwiązań. Staramy się też pokazać, że praca Tech Writera może być ciekawa i rozwijająca pod kątem umiejętności technicznych.
Available on
Apple Podcasts Logo
Google Podcasts Logo
Overcast Logo
Pocket Casts Logo
RadioPublic Logo
Spotify Logo
Currently playing episode

#31 Prosty jak budowa cepa, czyli Tech Writer tworzy generator stron statycznych

Tech Writer kodujeJul 03, 2021

00:00
27:37
#64 Tech Writer czepia się DITY, czyli jak tworzyć treść, która się dobrze wyszukuje

#64 Tech Writer czepia się DITY, czyli jak tworzyć treść, która się dobrze wyszukuje

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
Mar 27, 202434:49
#63 Tech Writer poznaje moc języka w produktach cyfrowych, czyli dlaczego UX writing jest ważny

#63 Tech Writer poznaje moc języka w produktach cyfrowych, czyli dlaczego UX writing jest ważny

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/
Feb 26, 202401:02:20
#62 Tech Writer sprawdza co w tech writingu piszczy, czyli rzut oka na ankietę od JetBrains

#62 Tech Writer sprawdza co w tech writingu piszczy, czyli rzut oka na ankietę od JetBrains

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
Jan 28, 202443:44
#61 Tech Writer zaczyna wdrażać semantic search, czyli kilka praktycznych wskazówek na początek

#61 Tech Writer zaczyna wdrażać semantic search, czyli kilka praktycznych wskazówek na początek

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
Dec 22, 202334:34
#60 Tech Writer chce być ponadczasowy, czyli które umiejętności warto posiadać, żeby nie wypaść z gry

#60 Tech Writer chce być ponadczasowy, czyli które umiejętności warto posiadać, żeby nie wypaść z gry

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
Nov 24, 202354:53
#59 Tech Writer wychodzi z mainstreamu, czyli migracja z WordPressa do Docusaurusa i GitHuba

#59 Tech Writer wychodzi z mainstreamu, czyli migracja z WordPressa do Docusaurusa i GitHuba

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/
Nov 05, 202328:08
#58 Tech Writer pracuje w zespole rozproszonym - wyzwania i rozwiązania

#58 Tech Writer pracuje w zespole rozproszonym - wyzwania i rozwiązania

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/
Oct 07, 202348:31
#57 Tech Writer zostaje Prompt Engineerem, czyli nowa potencjalna ścieżka kariery dla technoskryby

#57 Tech Writer zostaje Prompt Engineerem, czyli nowa potencjalna ścieżka kariery dla technoskryby

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/
Aug 28, 202342:15
#56 Tech Writer robi inżynierię oprogramowania, czyli dobre praktyki prosto od Google

#56 Tech Writer robi inżynierię oprogramowania, czyli dobre praktyki prosto od Google

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
Aug 01, 202351:31
#55 Tech Writer ocenia dojrzałość dokumentacji, czyli technologiczne marzenia kontra rzeczywistość

#55 Tech Writer ocenia dojrzałość dokumentacji, czyli technologiczne marzenia kontra rzeczywistość

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
Jun 29, 202353:01
#54 Tech Writer jedzie na fali AI, czyli do czego może się przydać sztuczna inteligencja w komunikacji technicznej

#54 Tech Writer jedzie na fali AI, czyli do czego może się przydać sztuczna inteligencja w komunikacji technicznej

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/
May 28, 202341:60
#53 Tech Writer robi ContentOps, czyli jak holistycznie podejść do dokumentacji

#53 Tech Writer robi ContentOps, czyli jak holistycznie podejść do dokumentacji

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
Apr 24, 202301:00:04
#52 Od przybytku głowa też boli, czyli Tech Writer próbuje utrzymać dokumentację w ryzach

#52 Od przybytku głowa też boli, czyli Tech Writer próbuje utrzymać dokumentację w ryzach

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/


Apr 11, 202301:11:31
#51 Tech Writer buduje stronę dla podcastu, czyli praktyczne zastosowanie Next.js

#51 Tech Writer buduje stronę dla podcastu, czyli praktyczne zastosowanie Next.js

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
Feb 26, 202331:45
#50 Tech Writer bloguje z GitHub Issues, czyli nietuzinkowy sposób na platformę contentową

#50 Tech Writer bloguje z GitHub Issues, czyli nietuzinkowy sposób na platformę contentową

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/
Jan 26, 202341:41
#49 Tech Writer testuje narzędzia do mierzenia indeksu czytelności

#49 Tech Writer testuje narzędzia do mierzenia indeksu czytelności

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
Dec 22, 202235:45
#48 Tech Writer uczy się frontendu, czyli jak wykorzystać technologie webowe w dokumentacji

#48 Tech Writer uczy się frontendu, czyli jak wykorzystać technologie webowe w dokumentacji

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/
Nov 16, 202237:28
#47 Tech Writer zgłębia tajniki dostępności cyfrowej, czyli jak tworzyć dokumentację dla wszystkich

#47 Tech Writer zgłębia tajniki dostępności cyfrowej, czyli jak tworzyć dokumentację dla wszystkich

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/
Oct 13, 202252:11
#46 Zostań hakerem w służbie pokoju, czyli o "Hack for Peace" słów kilka

#46 Zostań hakerem w służbie pokoju, czyli o "Hack for Peace" słów kilka

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
Sep 15, 202212:09
#45 Tech Writer wybiera pomiędzy narzędziami open source a enterprise, czyli jak zbudować tech stack z przyszłością

#45 Tech Writer wybiera pomiędzy narzędziami open source a enterprise, czyli jak zbudować tech stack z przyszłością

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
Sep 06, 202238:05
#44 Rekrutacja Tech Writerów w praktyce, czyli prawie wszystko co trzeba wiedzieć o rynku pracy dla technoskrybów w Polsce

#44 Rekrutacja Tech Writerów w praktyce, czyli prawie wszystko co trzeba wiedzieć o rynku pracy dla technoskrybów w Polsce

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/
Aug 01, 202256:35
#43 Tech Writer buduje stronę z dokumentacją, czyli prosty przepis jak zacząć od zera

#43 Tech Writer buduje stronę z dokumentacją, czyli prosty przepis jak zacząć od zera

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
Jul 16, 202235:34
#42 Konferencja soap! 2022 - podsumowanie

#42 Konferencja soap! 2022 - podsumowanie

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/
Jun 14, 202243:11
#41 Tech Writer rozważa podobieństwa i różnice między kodowaniem a pisaniem dokumentacji

#41 Tech Writer rozważa podobieństwa i różnice między kodowaniem a pisaniem dokumentacji

"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/
May 02, 202237:52
#40 Tech Writer spełnia swoje marzenia, czyli co i jak można zautomatyzować

#40 Tech Writer spełnia swoje marzenia, czyli co i jak można zautomatyzować

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
Mar 17, 202254:24
#39 DITA as code, czyli klasyczny standard w nowoczesnym wydaniu

#39 DITA as code, czyli klasyczny standard w nowoczesnym wydaniu

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
Feb 14, 202244:56
#38 Tech Writer walczy z hakerami, czyli jak zadbać o bezpieczeństwo dokumentacji

#38 Tech Writer walczy z hakerami, czyli jak zadbać o bezpieczeństwo dokumentacji

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
Jan 10, 202246:12
#37 Tech Writer potrzebuje więcej dynamiki, czyli zbyt statyczne strony z dokumentacją

#37 Tech Writer potrzebuje więcej dynamiki, czyli zbyt statyczne strony z dokumentacją

Dostarczanie statycznych stron z dokumentacją ostatnimi czasy wraca do łask. Prawdopodobnie dlatego, że takie strony są szybkie, bezpieczne i łatwe w serwowaniu. Jednak w niektórych sytuacjach mogą nas też ograniczać i sprawiać, że aktualizowanie ich zawartości staje się czasochłonne i problematyczne. Rozmawiamy o tym kiedy strony stają się zbyt statyczne i jak można temu zaradzić.

Muzyka w intro oraz dźwięki 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.

Informacje dodatkowe:

Strona statyczna (static site): https://slownik.intensys.pl/definicja/strona-statyczna/ 

Serwer aplikacji: https://pl.wikipedia.org/wiki/Serwer_aplikacji

Aplikacja internetowa/webowa: https://pl.wikipedia.org/wiki/Aplikacja_internetowa

DITA Open Toolkit: https://www.dita-ot.org/

Docusaurus: https://docusaurus.io/

Hugo: https://gohugo.io/

Gatsby: https://www.gatsbyjs.com/

Continuous Integration (CI)/Continuous Deployment (CD): https://en.wikipedia.org/wiki/CI/CD

"Git Branch": https://www.atlassian.com/git/tutorials/using-branches

Standard DITA (Darwin Information Typing Architecture): https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

Markdown: https://daringfireball.net/projects/markdown/syntax

Adobe FrameMaker: https://en.wikipedia.org/wiki/Adobe_FrameMaker

Oxygen XML Webhelp Responsive: https://www.oxygenxml.com/doc/versions/24.0/ug-webhelp-responsive/

Next.js: https://nextjs.org/

Node.js: https://nodejs.org/en/

Express.js: https://expressjs.com/

WordPress: https://wordpress.com/

Dec 06, 202131:17
#36 Tech Writer się boi, czyli Halloween Special 2021

#36 Tech Writer się boi, czyli Halloween Special 2021

Wszyscy czegoś się boją. Zdarza się, że nawiedzają nas koszmary i zjawy z przeszłości. Tech Writerzy nie są pod tym względem wyjątkiem. Mają swoje, nierzadko osobliwe, strachy. Z okazji Halloween rozmawiamy o tym czego boi się technoskryba i co nie daje mu spać po nocach. 

Uwaga: odcinek tylko dla ludzi o mocnych nerwach!

Informacje dodatkowe:

Grupa "Tworzenie dokumentacji" na Facebooku: https://www.facebook.com/groups/tworzeniedokumentacji

Microsoft Word: https://www.microsoft.com/pl-pl/microsoft-365/word

"Clippy": https://en.wikipedia.org/wiki/Office_Assistant

Subversion (SVN): https://subversion.apache.org/

Git: https://git-scm.com/

"Using Branches": https://svnbook.red-bean.com/en/1.7/svn.branchmerge.using.html

Gif "Git merge": https://gifer.com/en/7h7L

Git Cherry Pick: https://www.atlassian.com/git/tutorials/cherry-pick

Sphinx: https://www.sphinx-doc.org/en/master/

Jamstack: https://jamstack.org/

Python: https://www.python.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/

"Simplified User Interface: The Beginner’s Guide": https://www.techsmith.com/blog/simplified-user-interface/

"Rethink your screenshots and tutorials with a SUI", Anton Bollen: https://www.youtube.com/watch?v=hbT5U63uKkg

Micromanagement: https://en.wikipedia.org/wiki/Micromanagement

Film "Kingsajz": https://pl.wikipedia.org/wiki/Kingsajz

"Writing is like sorting laundry -- practical advice for tackling documentation projects": https://idratherbewriting.com/2015/01/29/writing-is-like-sorting-laundry-practical-advice-for-tackling-documentation-projects/

Podręcznik stylu (style guide): http://techwriter.pl/podrecznik-stylu-stylrecznik/

TeamCity: https://www.jetbrains.com/teamcity/

Docker: https://www.docker.com/

bash: https://pl.wikipedia.org/wiki/Bash

Syndrom oszusta: https://pl.wikipedia.org/wiki/Syndrom_oszusta

OpenID Connect: https://openid.net/connect/

OAuth 2.0: https://oauth.net/2/

JWT (JSON Web Tokens): https://jwt.io/

Serial comma/Oxford comma: https://en.wikipedia.org/wiki/Serial_comma

Stack Overflow: https://stackoverflow.com/

"The One Where Ross Got High", Friends: https://en.wikipedia.org/wiki/The_One_Where_Ross_Got_High

Oct 31, 202148:28
#35 Tech Writer chce kodować więcej
Oct 26, 202137:37
#34 Tech Writer dokumentuje, testuje, koduje, lokalizuje i projektuje, czyli człowiek renesansu w dokumentacji
Sep 07, 202127:15
#33 Kodować każdy może, czyli o Akademii Motorola Solutions słów kilka
Aug 18, 202131:53
#32 Tech Writer zatrudnia asystenta, czyli sztuczna inteligencja w służbie dokumentacji

#32 Tech Writer zatrudnia asystenta, czyli sztuczna inteligencja w służbie dokumentacji

Od dawna mówi się o tym, że maszyny zastąpią ludzi i zajmą ich miejsce jako korona stworzenia. Jednak zanim to nastąpi, możemy wykorzystać sztuczną inteligencję do własnych celów. Przyglądamy się obecnie dostępnym modelom językowym, a szczególnie GPT-3, rozmawiamy o tym co potrafią i rozważamy jak można by je wykorzystać w tworzeniu dokumentacji technicznej.

Czy kodujący Tech Writer może zrobić ze sztucznej inteligencji swojego asystenta? Co mógłby robić taki asystent? Co jest najbardziej wartościowe w pracy Tech Writera, a które obowiązki warto cedować na algorytmy? Jak praktycznie się za to zabrać?

Muzyka w intro oraz dźwięki 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.

Informacje dodatkowe:

Sztuczna inteligencja: https://pl.wikipedia.org/wiki/Sztuczna_inteligencja

Generative Pre-trained Transformer 3 (GPT-3): https://en.wikipedia.org/wiki/GPT-3

OpenAI: https://openai.com/

"#9 Robot dokumentuje, czyli technical writing przyszłości": https://techwriterkoduje.pl/blog/2019/10/17/robot-dokumentuje

"#11 Robot dokumentuje część 2 - automatyzacja kontra ludzie": https://techwriterkoduje.pl/blog/2019/12/12/robot-dokumentuje-czesc-2

Layout generator: https://twitter.com/sharifshameem/status/1282676454690451457?s=20

Natural Language Shell: https://beta.openai.com/?app=productivity&example=4_2_0

Summarization: https://beta.openai.com/?app=content-consumption&example=5_2_0

Semantic search: https://beta.openai.com/?example=0_2_0

GitHub Copilot: https://copilot.github.com/

"Copilot writes a text-based game in Python": https://sandyuraz.com/blogs/copilot-game/

Pamięć tłumaczeniowa: https://pl.wikipedia.org/wiki/Pami%C4%99%C4%87_t%C5%82umaczeniowa

"Dear Mr. Robot", Marta Bartnicka & Wojciech Froelich (soap! 2018): https://www.youtube.com/watch?v=Q_if0yBogUQ

Techwriter.pl: http://techwriter.pl/

"Going from A to C, a Practical Approach to Semantic Search", Paweł Kowaluk: https://www.slideshare.net/PawelKowaluk/semantic-search-40766546

Repozytorium GPT-2 na GitHub: https://github.com/openai/gpt-2

Jul 29, 202141:32
#31 Prosty jak budowa cepa, czyli Tech Writer tworzy generator stron statycznych
Jul 03, 202127:37
#30 Tech Writer radzi sobie ze sprzężeniem zwrotnym, czyli feedback do dokumentacji

#30 Tech Writer radzi sobie ze sprzężeniem zwrotnym, czyli feedback do dokumentacji

Naszą dokumentację możemy poprawić tylko wtedy jeśli wiemy jakie kryją się w niej problemy. Warto zbierać i analizować dane od użytkowników, a przede wszystkim pytać ich o opinię. Nie jest to bynajmniej proste zadanie, dlatego połączyliśmy siły z Rafałem Pawlickim, żeby porozmawiać o celach, sposobach, wyzwaniach i dobrych praktykach związanych z procesem zbierania informacji na temat dokumentacji od użytkowników. Staramy się też odpowiedzieć na odwieczne pytanie - jaki jest najlepszy polski odpowiednik słowa "feedback"?

Muzyka w intro oraz dźwięki 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.

Informacje dodatkowe:

"Feedback" w Słowniku Języka Polskiego: https://sjp.pl/feedback

Bounce rate: https://support.google.com/analytics/answer/1009409?hl=en

"Docs as code", Write the Docs:  https://www.writethedocs.org/guide/docs-as-code/

Dokumentacja Microsoft: https://docs.microsoft.com/

Usability Testing: https://en.wikipedia.org/wiki/Usability_testing

"Meet Content po raz pierwszy - relacja": http://techwriter.pl/meet-content-po-raz-pierwszy-relacja/

Card sorting: https://en.wikipedia.org/wiki/Card_sorting

Yandex Metrica: https://metrica.yandex.com/

"What is an Exit Page? (And How to View it in Google Analytics)": https://www.monsterinsights.com/what-is-an-exit-page-and-how-to-view-it-in-google-analytics/

Atlassian Jira: https://www.atlassian.com/software/jira

Google Forms: https://www.google.com/forms/about/

SurveyMonkey: https://www.surveymonkey.com/

"Wyniki badania płac w komunikacji technicznej 2020": http://techwriter.pl/wyniki-badania-plac-w-komunikacji-technicznej-2020/

Rafał Pawlicki (profil LinkedIn): https://pl.linkedin.com/in/rafa%C5%82-pawlicki-973281165

May 19, 202101:20:28
#29 Tech Writer koduje według dobrych praktyk

#29 Tech Writer koduje według dobrych praktyk

Pewnego dnia czujesz nieodpartą chęć napisania jakiegoś skryptu. Otwierasz edytor, tworzysz nowy plik i w pocie czoła dodajesz kolejne linijki kodu. Zachowujesz zmiany, wprowadzasz poprawki, weryfikujesz swoje dzieło i powtarzasz cały proces aż po pewnym czasie udaje Ci się doprowadzić skrypt do stanu, w którym robi to co chcesz. Cel osiągnięty. Niby tak, ale czy taki sposób tworzenia kodu jest właściwy? 

Rozmawiamy o dobrych praktykach, które kodujący Tech Writer może wdrożyć, żeby łatwiej tworzyć, utrzymywać, zmieniać, ulepszać i udostępniać swoje skrypty i aplikacje.

Muzyka w intro oraz dźwięki 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.

Informacje dodatkowe:

Notepad++: https://notepad-plus-plus.org/

Visual Studio (VS) Code: https://code.visualstudio.com/

Git: https://git-scm.com/

Bitbucket: https://bitbucket.org/

GitHub: https://github.com/

GitLab: https://about.gitlab.com/

Pull request w Bitbucket: https://www.atlassian.com/git/tutorials/making-a-pull-request

Subversion (SVN): https://pl.wikipedia.org/wiki/Subversion

Test-driven development: https://pl.wikipedia.org/wiki/Test-driven_development

DITA Open Toolkit: https://www.dita-ot.org/

Lint: https://en.wikipedia.org/wiki/Lint_(software)

Sourcery: https://sourcery.ai/

PyCharm: https://www.jetbrains.com/pycharm/

IntelliJ IDEA: https://www.jetbrains.com/idea/

Cyclomatic complexity: https://en.wikipedia.org/wiki/Cyclomatic_complexity

Wily: https://wily.readthedocs.io/en/latest/

Programowanie funkcyjne: https://pl.wikipedia.org/wiki/Programowanie_funkcyjne

Apr 08, 202129:46
#28 Tech Writer wybiera narzędzie do kodowania, czyli VS Code kontra IntelliJ IDEA

#28 Tech Writer wybiera narzędzie do kodowania, czyli VS Code kontra IntelliJ IDEA

Co jest lepsze do pisania kodu - komercyjne środowisko programistyczne czy darmowy edytor kodu źródłowego? Czy takie porównanie w ogóle ma sens?

Michał na co dzień pracuje w IntelliJ IDEA, a Paweł, jak spora część programistów, w VS Code. W tej subiektywnej rozmowie na bardzo subiektywny temat nie staramy się rozstrzygnąć, która aplikacja jest lepsza. Zamiast tego opowiadamy o tym dlaczego zaczęliśmy używać właśnie tych rozwiązań, co w nich lubimy, a co nam przeszkadza i w jakich sytuacjach według nas najlepiej się sprawdzają.

Muzyka w intro oraz dźwięki 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.

Informacje dodatkowe:

Stack Overflow Developer Survey 2019: https://insights.stackoverflow.com/survey/2019

Stack Overflow Developer Survey 2020: https://insights.stackoverflow.com/survey/2020

Visual Studio (VS) Code: https://code.visualstudio.com/

IntelliJ IDEA: https://www.jetbrains.com/idea/

IntelliJ IDEA - porównanie wersji Ultimate i Community: https://www.jetbrains.com/idea/features/editions_comparison_matrix.html

Zintegrowane środowisko programistyczne (IDE): https://pl.wikipedia.org/wiki/Zintegrowane_%C5%9Brodowisko_programistyczne

Edytor kodu źródłowego: https://pl.wikipedia.org/wiki/Edytor_kodu_%C5%BAr%C3%B3d%C5%82owego

IDEs vs Code Editors: https://realpython.com/lessons/ides-vs-code-editors/

JavaScript: https://developer.mozilla.org/pl/docs/Web/JavaScript

Cascading Style Sheets (CSS): https://developer.mozilla.org/pl/docs/Learn/Getting_started_with_the_web/CSS_basics

React: https://pl.reactjs.org/

Node.js: https://nodejs.org/en/

Python: https://www.python.org/

Kotlin: https://kotlinlang.org/

Java: https://java.com/en/

TeamCity: https://www.jetbrains.com/teamcity/

Docker: https://www.docker.com/

Standard DITA (Darwin Information Typing Architecture): https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

Prettier: https://prettier.io/

Szkolenie "Modern Python Projects", Sebastian Witowski: https://training.talkpython.fm/courses/modern-python-projects

PyCharm: https://www.jetbrains.com/pycharm/

Language Server Protocol: https://en.wikipedia.org/wiki/Language_Server_Protocol

Vim: https://pl.wikipedia.org/wiki/Vim

VSCodium: https://vscodium.com/

Mar 22, 202140:45
#27 Tech Writer szkoli się z Pythona

#27 Tech Writer szkoli się z Pythona

Chcesz lepiej rozumieć kod, który opisujesz? Chcesz zautomatyzować żmudne aspekty swojej pracy? Chcesz móc powiedzieć śmiało i dumnie - znam Pythona?

W tym odcinku rozmawiamy z Adrianem Gonciarzem, który prowadzi szkolenia z Pythona dla tech writerów i testerów, oraz Basią Czyż, technical writerką, która wzięła udział w tym szkoleniu.

Szkolenie odbyło się w pełni online i składało się z dwugodzinnych bloków trzy razy w tygodniu. W jego toku, uczestnicy stworzyli dwa projekty i nauczyli się solidnych podstaw Pythona. Od naszych gości dowiadujemy się jak szkolenie wygląda od kulis oraz jaką wiedzę można z niego wynieść. Dostajemy opinię organizatora i uczestnika, a przy tym jesteśmy świadkami bardzo ciekawej dyskusji o roli kodowania w pracy technical writera oraz o przyszłości tego zawodu.

Muzyka w intro oraz dźwięki 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.

Informacje dodatkowe:

Szkolenie "Python for Testers and Technical Writers": https://dredar.com/services/trainings-and-workshops/python-for-testers-and-technical-writers

Site Reliability Engineering (SRE): https://en.wikipedia.org/wiki/Site_reliability_engineering

DREDAR: https://dredar.com/

Techwriter.pl: http://techwriter.pl/

"Tech Writer koduje w Pythonie. Przewodnik szybkiego startu": https://techwriterkoduje.pl/docs/teoria

"Automate the Boring Stuff with Python": https://automatetheboringstuff.com/

"The PEP 8 Song", Leon Sandoy: https://www.youtube.com/watch?v=hgI0p1zf31k

"PEP 20 - The Zen of Python": https://www.python.org/dev/peps/pep-0020/

Sebastian Witowski, Python consultant and trainer: https://switowski.com/

Feb 17, 202156:15
#26 Tech Writerzy dokumentują API

#26 Tech Writerzy dokumentują API

Pisanie dokumentacji do API to dziedzina sama w sobie, która w dzisiejszych czasach zyskuje na znaczeniu. Przyspieszony rozwój technologii cyfrowych w dobie pandemii i pracy zdalnej podniósł znaczenie dokumentacji w ogóle, a dokumentacji do API w szczególności.

Z naszymi gośćmi, Jadwigą Sitnicką z LogMeIn, Mateuszem Wiktorem z PubNub i Pawłem Krentowskim z Ocado Technology, rozmawiamy m.in. o tym z jakich elementów składa się dokumentacja do API, kto i w jaki sposób tworzy poszczególne części, jakie są najczęstsze problemy i wyzwania podczas tworzenia tego typu dokumentacji oraz jakie narzędzia warto znać.

Muzyka w intro oraz dźwięki 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.

Informacje dodatkowe:

Application Programming Interface (API): https://pl.wikipedia.org/wiki/Interfejs_programowania_aplikacji

LogMeIn: https://www.logmein.com/

Ocado Technology: https://www.ocadogroup.com/technology/technology-pioneers

PubNub: https://www.pubnub.com/

"The State of API Report 2020": https://smartbear.com/resources/ebooks/the-state-of-api-2020-report/

Markdown: https://daringfireball.net/projects/markdown/syntax

ReadMe.io: https://readme.com/

Stoplight Studio: https://stoplight.io/studio/

OpenAPI: https://www.openapis.org/

Swagger UI: https://swagger.io/tools/swagger-ui/

ReDoc: https://github.com/Redocly/redoc

Jekyll: https://jekyllrb.com/

GitLab: https://about.gitlab.com/

curl: https://curl.se/

Postman: https://www.postman.com/

Visual Studio Code: https://code.visualstudio.com/

Software Development Kit (SDK): https://pl.wikipedia.org/wiki/Software_development_kit

Integrated Development Environment (IDE): https://pl.wikipedia.org/wiki/Zintegrowane_%C5%9Brodowisko_programistyczne

"Wstęp do REST API": https://devszczepaniak.pl/wstep-do-rest-api/

Grupa "Tworzenie dokumentacji" na Facebooku: https://www.facebook.com/groups/tworzeniedokumentacji

Feb 10, 202101:48:21
#25 Tech Writer koduje w dokumentacji, czyli Markdown w wersji rozszerzonej

#25 Tech Writer koduje w dokumentacji, czyli Markdown w wersji rozszerzonej

Markdown to prosty i lekki język znaczników, który w ostatnich latach zyskał sporą popularność, szczególnie w świecie dokumentacji dla programistów. Pozwala nam on łatwo i szybko stworzyć tekst, a następnie opublikować go jako HTML. Z biegiem czasu pojawiły się różne odmiany i rozszerzenia Markdowna, pozwalające wycisnąć z niego jeszcze więcej. Jednym z nich jest MDX, który pozwala na używanie bezpośrednio w tekście elementów JSX. Takie rozwiązanie otwiera przed nami nowe możliwości, jak na przykład opcję umieszczenia w dokumentacji interaktywnej próbki kodu. Dzięki temu możemy przesunąć naszą dokumentację na wyższy poziom. Rozmawiamy o tym czym jest MDX, jakie daje nam możliwości i w jakich sytuacjach może nam się przydać.

Muzyka w intro oraz dźwięki 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.

Informacje dodatkowe:

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 v2: https://v2.docusaurus.io/

Gatsby: https://www.gatsbyjs.com/

Next.js: https://nextjs.org/

Create React app: https://github.com/facebook/create-react-app

Carbon React: https://react.carbondesignsystem.com/

React Bootstrap: https://react-bootstrap.github.io/

Swagger UI: https://swagger.io/tools/swagger-ui/

webpack: https://webpack.js.org/

Jan 21, 202126:60
#24 Tech Writer publikuje inaczej, czyli API do dokumentacji

#24 Tech Writer publikuje inaczej, czyli API do dokumentacji

Niektóre sposoby publikowania dokumentacji są znane wśród Tech Writerów od zarania dziejów. Portale serwujące wszelakiej maści treści w formacie HTML czy PDF są niejako standardem branżowym. W sytuacji kiedy odbiorcą dokumentacji jest użytkownik produktu te formy spełniają swoje zadanie. Ale co zrobić kiedy do naszej dokumentacji potrzebuje się dobrać jakaś aplikacja? Na przykład, aplikacja webowa chce wyświetlić dokumentację w panelu, który jest jej integralną cześcią. Możemy wtedy zastosować stary dobry "iframe", jednak takie rozwiązanie nie jest zalecane, a do tego stwarza szereg problemów. A może by tak stworzyć API dla dokumentacji i serwować treść za pomocą endpointów? Rozważamy czy takie rozwiązanie jest możliwe, czy ma sens i w jakich sytuacjach mogłoby się sprawdzić.

Informacje dodatkowe:

Application Programming Interface (API): https://pl.wikipedia.org/wiki/Interfejs_programowania_aplikacji

Tag : https://www.w3schools.com/tags/tag_iframe.ASP

Progressive Web Application: https://en.wikipedia.org/wiki/Progressive_web_application

"Co zmieniają Progressive Web Applications? Wszystko, co musisz wiedzieć o PWA": https://www.e-point.pl/blog/co-zmieniaja-progressive-web-applications-wszystko-co-musisz-wiedziec-o-pwa

Elastic (Elasticsearch, Kibana): https://www.elastic.co/

Standard DITA (Darwin Information Typing Architecture): https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

Adobe FrameMaker: https://pl.wikipedia.org/wiki/Adobe_FrameMaker

Markdown: https://daringfireball.net/projects/markdown/syntax

Gatsby: https://www.gatsbyjs.com/

GraphQL: https://graphql.org/

React: https://pl.reactjs.org/

Dec 23, 202030:44
#23 Tech Writer mierzy jakość dokumentacji, czyli co i jak sprawdzać

#23 Tech Writer mierzy jakość dokumentacji, czyli co i jak sprawdzać

Jak zrobić najlepszą dokumentację? Ustalamy wewnętrzne standardy i się ich trzymamy, a potem sprawdzamy czy dokumentacja spełnia swoje cele. Następnie weryfikujemy standardy, żeby nasza dokumentacja spełniała założone cele coraz lepiej.

Wydaje się proste, ale diabeł tkwi w szczegółach. Z Rafałem Pawlickim zastanawiamy się jak utrzymywać wewnętrzne standardy jednocześnie ucząc ludzi pisania dobrej dokumentacji oraz w jaki sposób mierzyć efektywność dokumentacji. Rozmawiamy o tym jak stworzyć model oceny dokumentacji pod kątem jakości i dojrzałości, a następnie jak wykorzystać te informacje do planowania pracy dokumentacyjnej. Przyglądamy się też zbieraniu danych od użytkowników oraz wykorzystywaniu ich do wdrażania zmian w organizacji.

Które metryki najlepiej sprawdzały się dla nas do tej pory? Które działają najlepiej osobno, a które w połączeniu? Które elementy może sprawdzać automat, a które powinny być weryfikowane przez człowieka? Posłuchajcie, a potem dajcie nam znać jakie Wy macie sposoby i pomysły na mierzenie jakości dokumentacji.

Informacje dodatkowe:

Hemingway App: http://www.hemingwayapp.com/

LanguageTool: https://languagetool.org/

Readability indices: https://www.analyzemywriting.com/readability_indices.html

Konferencja Write the Docs 2020 w Pradze: https://www.writethedocs.org/conf/prague/2020/ 

 "Organizing a Confluence hoard, or, does this page spark joy?", Abigail Sutherland: https://www.youtube.com/watch?v=DrGCWTxeA94&list=PLZAeFn6dfHpmRWZJaUwQzsdagW2TtRI2x&index=3

"The Importance of Using Analytics and Feedback for your Documentation", Karissa Van Baulen: https://www.youtube.com/watch?v=EkPU2afWPDA&list=PLZAeFn6dfHpmRWZJaUwQzsdagW2TtRI2x&index=13

Google Analytics: https://analytics.google.com/analytics/web/provision/#/provision

Google Tag Manager: https://marketingplatform.google.com/about/tag-manager/

Nov 23, 202001:04:40
#22 Tech Writer buduje dokumentację API, czyli Next.js, ReDoc i OpenAPI w akcji
Oct 18, 202035:57
#21 Tech Writer zbiera informacje ze stron, czyli jak można wykorzystać web scraping

#21 Tech Writer zbiera informacje ze stron, czyli jak można wykorzystać web scraping

Web scraping to zbieranie danych ze stron internetowych. Google, na przykład, robi to, żeby indeksować cały internet w swojej wyszukiwarce. Web scraping wykorzystuje się też do monitorowania cen w konkurencyjnych sklepach internetowych.

U nas w firmie używamy web scrapingu, żeby indeksować dokumentację dla naszej wyszukiwarki. To samo rozwiązanie wykorzystujemy też, żeby sprawdzać czy wszystkie linki działają. Wyniki web scrapingu zapisujemy  w Elasticsearchu, a potem analizujemy je za pomocą raportów i filtrów  w Kibanie. Dzięki temu stworzyliśmy zalążek panelu kontrolnego, na którym widać aktualną jakość naszej dokumentacji.

W niedalekiej przyszłości chcemy  rozszerzyć nasze rozwiązanie o dodatkowe funkcje. Planujemy, na przykład, testować strony pod kątem wymaganych elementów i zgodności z regułami  naszego style guide’a. Kolejną opcją jest sprawdzanie czy w treści nie ma błędów gramatycznych i stylistycznych oraz czy język, którego używamy do tworzenia instrukcji jest wystarczająco przejrzysty.

Co można jeszcze zrobić za pomocą web scrapingu? Jakie inne testy są potrzebne w świecie dokumentacji technicznej i pisania ustrukturyzowanego? Zapraszamy do słuchania.

Informacje dodatkowe:

Web scraping: https://en.wikipedia.org/wiki/Web_scraping

Scrapy: https://scrapy.org/

Elastic (Elasticsearch, Kibana): https://www.elastic.co/

curl: https://curl.haxx.se/

Textstat: https://github.com/shivam5992/textstat

spaCy: https://spacy.io/

Selenium: https://www.selenium.dev/

TestCafe: https://devexpress.github.io/testcafe/

Vale: https://github.com/errata-ai/vale

Sep 15, 202032:54
#20 Tech Writer optymalizuje, czyli web performance w dokumentacji
Aug 06, 202037:07
#19 Tech Writer pracuje zdalnie, czyli jak to się robi w GitLabie
Jul 08, 202053:47
#18 Wyboista droga do kodowania
Jun 09, 202048:12
#17 Webhelp kontra Progressive Web App
May 18, 202030:41
#16 DITA z Gita
Apr 22, 202033:15
#15 Technoskryby potyczki z SME, czyli jak zdobywać informacje potrzebne do tworzenia dokumentacji

#15 Technoskryby potyczki z SME, czyli jak zdobywać informacje potrzebne do tworzenia dokumentacji

Jak Technical Writer radzi sobie ze zdobywaniem informacji? Co jeśli Subject Matter Expert (SME) jest niedostępny? A co jeśli dwóch SME nie może się zgodzić co jest najważniejsze? Rozmawiamy z Mateuszem Boryckim, który przynosi cztery prawdziwe historie (case studies) z życia Technical Writera.

Apr 07, 202001:06:10