Tech Writer koduje

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

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

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:

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/

"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/

"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

Czy Tech Writer, który trochę koduje może kodować więcej? Jakie ma opcje rozwoju zawodowego jeśli interesują go głównie skrypty, narzędzia i inne techniczne aspekty tworzenia dokumentacji?

Bazując na własnych doświadczeniach, rozważamy trzy możliwe scenariusze dla technoskrybów z zapędami programistycznymi. Pojawia się też kilka czerstwych żartów i nawiązań do zamierzchłych czasów.

Informacje dodatkowe:

MadCap Flare: https://www.madcapsoftware.com/products/flare/

Visual Basic for Applications:

Perl: https://www.perl.org/

Arbortext: https://www.ptc.com/en/products/arbortext

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

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

Front-end i back-end: https://pl.wikipedia.org/wiki/Front-end_i_back-end

gulp.js: https://gulpjs.com/

Svelte: https://svelte.dev/

Teleturniej "Idź na całość": https://pl.wikipedia.org/wiki/Id%C5%BA_na_ca%C5%82o%C5%9B%C4%87

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

Oct 26, 202137:37

#34 Tech Writer dokumentuje, testuje, koduje, lokalizuje i projektuje, czyli człowiek renesansu w dokumentacji

Czym na co dzień zajmuje się Technical Writer? A może lepiej zapytać czym się nie zajmuje?

Patrycja Pyrek studiuje informatykę i ekonometrię, uczy języka japońskiego i jednocześnie jako stażystka zdobywa techwriterskie doświadczenie. Ta różnorodność zainteresowań przejawia się również podczas jej stażu. Patrycja, poza tworzeniem dokumentacji, ma jeszcze szereg innych zadań, które pozwalają jej się rozwijać w obszarach testowania, lokalizacji i projektowania. Zresztą posłuchajcie sami!

Informacje dodatkowe:

Selenium WebDriver: https://www.selenium.dev/documentation/webdriver/

Protractor: https://www.protractortest.org/

AngularJS: https://angularjs.org/

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

Sep 07, 202127:15

#33 Kodować każdy może, czyli o Akademii Motorola Solutions słów kilka

Czy w kilka miesięcy można nauczyć się kodowania i zostać zatrudnionym jako młodszy programista w międzynarodowej korporacji? Dzięki Akademii Motorola Solutions taki scenariusz jest możliwy. Na początku sierpnia 2021 wystartowała druga edycja tego programu szkoleniowego stworzonego dla osób, które marzą o zmianie kariery i wejściu do świata IT. W tym odcinku rozmawiamy z Jackiem Drabikiem, prezesem Motorola Solutions w Polsce, oraz Klaudią Rydzanicz i Pawłem Kózką, uczestnikami pierwszej edycji Akademii, m.in. o tym kto może wziąć udział w programie oraz jak wygląda rekrutacja i proces przygotowania do nowego zawodu.

Informacje dodatkowe:

O Akademii: https://pracawmotoroli.pl/o-akademii/

Aug 18, 202131:53

#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ć?

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

Generatorów stron statycznych jest całkiem sporo. Jednak nie jest to powód, dla którego Tech Writer miałby zrezygnować ze stworzenia swojego. A że technoskryba z natury lubi prostotę i przejrzystość to generator też musi mieć takie cechy. Rozmawiamy o tym dlaczego zdecydowaliśmy się na stworzenie własnego rozwiązania, jakiej technologii użyliśmy, co nam to dało i czy było to warte zachodu.

Informacje dodatkowe:

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

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

Embedded JavaScript Templates (EJS): https://ejs.co/

Static Site Generator: https://www.gatsbyjs.com/docs/glossary/static-site-generator/

Hydration (web development): https://en.wikipedia.org/wiki/Hydration_(web_development)

Docusaurus: https://docusaurus.io/

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

The Python Standard Library: https://docs.python.org/3/library/

Jinja: https://jinja.palletsprojects.com/en/3.0.x/

Template strings w Pythonie: https://docs.python.org/3/library/string.html#template-strings

JSON Schema: https://json-schema.org/

Jul 03, 202127:37

#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"?

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

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/

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

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ą.

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

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

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

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.

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

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ć.

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

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ć.

Informacje dodatkowe:

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

MDX: https://mdxjs.com/

Wprowadzenie do JSX: https://pl.reactjs.org/docs/introducing-jsx.html

"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/

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

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

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:

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

GraphQL: https://graphql.org/

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

Dec 23, 202030:44

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

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

Next.js to framework Reacta, dzięki któremu można w elastyczny sposób tworzyć nowoczesne strony internetowe. Według rankingu na stronie staticgen.com, jest to również jeden z najpopularniejszych generatorów stron statycznych. Rozmawiamy o tym jak można połączyć Next.js z narzędziem ReDoc, żeby zbudować stronę z dokumentacją dla wielu API stworzonych przy pomocy specyfikacji OpenAPI. Zastanawiamy się też jak Next.js może nam się przydać kiedy piszemy dokumentację w standardzie DITA.

Informacje dodatkowe:

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

Static Site Generator: https://www.gatsbyjs.com/docs/glossary/static-site-generator/

StaticGen: https://www.staticgen.com/

Docusaurus: https://docusaurus.io/

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

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

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

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

swagger-ui-react: https://www.npmjs.com/package/swagger-ui-react

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

Wtyczki dla DITA OT: https://www.dita-ot.org/plugins

Wtyczka Swagger dla DITA OT: https://github.com/jason-fox/fox.jason.passthrough.swagger

Oct 18, 202035:57

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

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

Wydajność to temat rzadko poruszany w tech writingu, pomimo tego, że webowa forma dokumentacji jest bardzo popularna. Czy szybkość ładowania stron ma znaczenie dla naszych odbiorców? A jeśli tak, to czy Tech Writer ma jakiś wpływ na wydajność dokumentacji? Rozmawiamy o tym jak mierzyć i poprawiać web performance. Zastanawiamy się co może zrobić w tej kwestii Tech Writer, a co musi wdrożyć programista lub inżynier DevOps. Wreszcie rozmawiamy o tym, że w dokumentacji performance to nie wszystko.

Informacje dodatkowe:

Web performance: https://en.wikipedia.org/wiki/Web_performance

"How to Improve Your Page Load Speed by 70.39% in 45 Minutes": https://www.ventureharbour.com/improving-site-speed/

TinyPNG: https://tinypng.com/

ImageMagick: https://imagemagick.org/index.php

Gzip: https://www.gnu.org/software/gzip/

Chunking w standardzie DITA: https://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/chunking.html

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

HTTP caching: https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching

WordPress: https://wordpress.com

"What Are Static Site Generators?": https://www.netguru.com/blog/what-are-static-site-generators

Google PageSpeed Insights: https://developers.google.com/speed/pagespeed/insights/

Google Lighthouse: https://developers.google.com/web/tools/lighthouse

Docusaurus: https://docusaurus.io/

Aug 06, 202037:07

#19 Tech Writer pracuje zdalnie, czyli jak to się robi w GitLabie

Trwająca od kilku miesięcy sytuacja spowodowała, że biura zostały pozamykane a praca zdalna z dnia na dzień stała się nowym standardem. Jednak istnieją też takie firmy, które już na wczesnym etapie rozwoju podjęły świadomą decyzję, że postawią na model pracy bez tradycyjnych biur. O byciu w pełni zdalnym Technical Writerem rozmawiamy z Marcinem Sędłakiem-Jakubowskim z firmy GitLab. Pytamy o procesy, narzędzia, budowanie relacji i staramy się ustalić czy jest w tym wszystkim jakiś haczyk.

Informacje dodatkowe:

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

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

GitLab Unfiltered: https://www.youtube.com/channel/UCMtZ0sc1HHNtGGWZFDRTh5A

All-Remote Meetings: https://about.gitlab.com/company/culture/all-remote/meetings/

Creating GitLab’s remote playbook: https://changelog.com/podcast/397

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

Manjaro Linux: https://manjaro.org/

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

Vim: https://www.vim.org/

Nanoc: https://nanoc.ws/

Jul 08, 202053:47

#18 Wyboista droga do kodowania

Przejście od zera do kodującego Tech Writera to dość długa droga, i nie zawsze usłana różami. Jednak przy odpowiedniej motywacji i podejściu można podołać temu wyzwaniu. Rozmawiamy o tym jak zacząć naukę kodowania, przez jakie etapy trzeba przejść i jak radzić sobie z problemami i pułapkami.

Informacje dodatkowe:

Why Learning To Code Is So Damn Hard: https://www.thinkful.com/blog/why-learning-to-code-is-so-damn-hard/

Skillshare: https://www.skillshare.com/

Codecademy: https://codecademy.dev/

Stack Overflow: https://stackoverflow.com/

Jun 09, 202048:12

#17 Webhelp kontra Progressive Web App

Offline help, który sam się aktualizuje. Czy to w ogóle możliwe? Zastanawiamy się czy webhelp czasy świetności ma już za sobą i czy Progressive Web App (PWA) ma szansę zostać nowym królem helpów.

Informacje dodatkowe:

HTML Help: https://pl.wikipedia.org/wiki/HTML_Help

"About Webhelp Output" (pomoc MadCap Flare 2017r3): https://help.madcapsoftware.com/flare2017r2/Content/Output/Flare/WebHelp-Output/About-WebHelp-Output.htm

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

Oxygen Webhelp: https://www.oxygenxml.com/xml_editor/webhelp.html

May 18, 202030:41

#16 DITA z Gita

Czy szanujący się zespół dokumentacyjny używający standardu DITA może działać bez CCMSa? Czy Technical Writer odnajdzie się w gicie? Jakie wyzwania stwarza taka implementacja? Techniczna rozmowa o technical writingu.

Informacje dodatkowe:

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

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

DITA for Small Teams: http://www.d4st.org/

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

Poetry: https://python-poetry.org/

Gradle: https://gradle.org/

Lightweight DITA: http://docs.oasis-open.org/dita/LwDITA/v1.0/cn01/LwDITA-v1.0-cn01.pdf

Oxygen XML: https://www.oxygenxml.com/

Schematron: http://schematron.com/

Apache Ant: https://ant.apache.org/

Extensible Stylesheet Language Transformations (XSLT): https://pl.wikipedia.org/wiki/XSL_Transformations

Pytest: https://docs.pytest.org/en/latest/

Git submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules

Continuous integration (CI): https://en.m.wikipedia.org/wiki/Continuous_integration

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

npm: https://www.npmjs.com/

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

Bitbucket: https://bitbucket.org/

Progressive Web Apps: https://web.dev/what-are-pwas/

Prince XML: https://www.princexml.com/

Apr 22, 202033:15

#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

#14 Tech Writer zaczyna kodować w Pythonie, czyli o narzędziach i dobrych praktykach

Rozmawiamy z Sebastianem Witowskim o tym jak ustawić sobie środowisko do kodowania w Pythonie i jakich błędów unikać zaczynając swoją przygodę z tym językiem programowania. Spora dawka wiedzy dla początkujących Pythonistów. Ale jeśli kodujesz w Pythonie od jakiegoś czasu i chcesz się upewnić, że stosujesz dobre praktyki, to ten odcinek jest też dla Ciebie.

Informacje dodatkowe:

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

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

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

Vim: https://www.vim.org/

pyenv: https://github.com/pyenv/pyenv

Python venv: https://docs.python.org/3/library/venv.html

Python virtualenv: https://virtualenv.pypa.io/en/stable/

Conda: https://docs.conda.io/en/latest/

Node modules: https://www.w3schools.com/nodejs/nodejs_modules.asp

Pipenv: https://pipenv.readthedocs.io/en/latest/

Poetry: https://python-poetry.org/

Python Requests: https://2.python-requests.org/en/master/

Django: https://www.djangoproject.com/

Flask: https://flask.palletsprojects.com/en/1.1.x/

EuroPython 2019: https://ep2019.europython.eu/

Cookiecutter: https://cookiecutter.readthedocs.io/en/1.7.0/

Pipx: https://github.com/pipxproject/pipx

Black: https://github.com/psf/black

npm: https://www.npmjs.com/

npx: https://www.npmjs.com/package/npx

"The Hitchhiker’s Guide to Python!", Kenneth Reitz, Tanya Schlusser: https://docs.python-guide.org/

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

Write the Docs: https://www.writethedocs.org/

Pytest: https://docs.pytest.org/en/latest/

Python unittest: https://docs.python.org/3.8/library/unittest.html

Test Driven Development (TDD): https://www.agilealliance.org/glossary/tdd/

Konferencja soap!: http://soapconf.com/

Warsztat "Modern Python Developer's Toolkit": https://www.meetup.com/Pykonik/events/268809734/

Pykonik, Kraków Python User Group: https://www.meetup.com/Pykonik/

Profil Sebastiana na LinkedIn: https://www.linkedin.com/in/switowski/

Profil Sebastiana na Twitterze: https://twitter.com/SebaWitowski

Strona Sebastiana: https://switowski.com/

Mar 24, 202050:08

#13 Full-Stack Tech Writer, czyli technoskryba kontra chmura

Jakie są obowiązki Technical Writera? Pewnie większość z Was odpowiedziałaby, że pisanie dokumentacji. A co z budowaniem stron i hostowaniem ich w chmurze? Damy sobie z tym radę? Ten odcinek to nie rozważania teoretyczne, ale oparta na faktach historia o tym jak trzech Technical Writerów ogarnęło cały stack technologiczny i devops dla portalu z dokumentacją.

Informacje dodatkowe:

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

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

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

Component content management system (CCMS): https://en.wikipedia.org/wiki/Component_content_management_system

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

DeepL: https://www.deepl.com/translator

Scrapy: https://scrapy.org/

Jinja2: https://jinja.palletsprojects.com/en/2.11.x/

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

Elasticsearch: https://www.elastic.co/

Kubernetes: https://kubernetes.io/

Feb 25, 202045:17

#12 Tech Writer się rekrutuje, czyli jak ważne są umiejętności techniczne

Czy ogłoszenie o pracę mówi Ci co będziesz robił jako Technical Writer? Jak pracodawca sprawdzi Twoje umiejętności? Co się liczy u Technical Writera? Rozmawiamy z Tomkiem Prusem o blaskach i cieniach rekrutowania Technical Writerów starając się odpowiedzieć na pytanie jak ważne w naszej profesji są umiejętności techniczne.

Jan 20, 202054:22

#11 Robot dokumentuje część 2 - automatyzacja kontra ludzie

Spotkaliśmy się z Agatą Rygielską i rozmawialiśmy o wpływie automatyzacji na ludzi i ich pracę. Agata jest Technical Writerką od 2 lat, a wcześniej pracowała w branży tłumaczeniowej. Widziała jak automatyzacja doprowadziła do marginalizacji "białkowych" tłumaczy. Jej doświadczenia doprowadziły nas do rozważań o przyszłości komunikacji technicznej. Czy przyszłość rysuje się optymistycznie dla Technical Writerów, czy raczej w ciemnych barwach?

Informacje dodatkowe:

MadCap Software: https://www.madcapsoftware.com/

Konferencja Tłumaczy: https://www.konferencjatlumaczy.pl/

Dec 12, 201951:13

#10 Docusaurus - Tech Writer dokarmia dinozaury

Docusaurus to static site generator stworzony przez Facebooka, którego główną zaletą jest prostota. Rozmawiamy o tym co oferuje to narzędzie, jakie są jego mocne i słabe strony oraz w jakich sytuacjach może się sprawdzić jako rozwiązanie do tworzenia dokumentacji.

Informacje dodatkowe:

Docusaurus: https://docusaurus.io/

Using Docusaurus to Create Open Source Websites: https://www.youtube.com/watch?v=QcGJsf6mgZE