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

Posłuchaj

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

Posłuchaj

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

Posłuchaj

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

Posłuchaj

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

Posłuchaj

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

Posłuchaj

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

Posłuchaj

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

Posłuchaj

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

Posłuchaj

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

Posłuchaj