Skip to main content

#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

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.

Posłuchaj

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

Posłuchaj

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

Posłuchaj