Tech Writer koduje
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.
Technologia
#24 Tech Writer publikuje inaczej, czyli API do dokumentacji
2020-12-23 14:30:45
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 <iframe>: 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/
#23 Tech Writer mierzy jakość dokumentacji, czyli co i jak sprawdzać
2020-11-23 14:14:46
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/
#22 Tech Writer buduje dokumentację API, czyli Next.js, ReDoc i OpenAPI w akcji
2020-10-18 21:50:38
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/
React: https://pl.reactjs.org/
Static Site Generator: https://www.gatsbyjs.com/docs/glossary/static-site-generator/
StaticGen: https://www.staticgen.com/
Docusaurus: https://docusaurus.io/
Gatsby: https://www.gatsbyjs.com/
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
#21 Tech Writer zbiera informacje ze stron, czyli jak można wykorzystać web scraping
2020-09-15 08:54:41
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/
#20 Tech Writer optymalizuje, czyli web performance w dokumentacji
2020-08-06 13:24:57
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/
#19 Tech Writer pracuje zdalnie, czyli jak to się robi w GitLabie
2020-07-08 20:44:38
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/
#18 Wyboista droga do kodowania
2020-06-09 13:24:28
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/
#17 Webhelp kontra Progressive Web App
2020-05-18 09:06:36
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
#16 DITA z Gita
2020-04-22 12:32:11
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/
Git: https://git-scm.com/
DITA for Small Teams: http://www.d4st.org/
Python: https://www.python.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/
Docker: https://www.docker.com/
Bitbucket: https://bitbucket.org/
Progressive Web Apps: https://web.dev/what-are-pwas/
Prince XML: https://www.princexml.com/
#15 Technoskryby potyczki z SME, czyli jak zdobywać informacje potrzebne do tworzenia dokumentacji
2020-04-07 12:19:48
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.