23 episodes

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.

Tech Writer koduje Doc Developer

    • Technology

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.

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

    • 1 hr 4 min
    #22 Tech Writer buduje dokumentację API, czyli Next.js, ReDoc i OpenAPI w akcji

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

    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

    • 35 min
    #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

    • 32 min
    #20 Tech Writer optymalizuje, czyli web performance w dokumentacji

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

    • 37 min
    #19 Tech Writer pracuje zdalnie, czyli jak to się robi w GitLabie

    #19 Tech Writer pracuje zdalnie, czyli jak to się 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/

    • 53 min
    #18 Wyboista droga do kodowania

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

    • 48 min

Top Podcasts In Technology