#53 Tech Writer robi ContentOps, czyli jak holistycznie podejść do dokumentacji

Witamy w podcaście Tech Writer Koduje, w którym mówimy o technicznej stronie tworzenia dokumentacji w IT. W dzisiejszym odcinku, tak jak w poprzednich wszystkich odcinkach, moim gościem jest Paweł Kowaluk. Dzień dobry, panie redaktorze. Który jest ekspertem od ContentOps. Ale zanim zaczniemy mówić, co to jest ContentOps, po co to robić, jakie są główne benefity, to chciałbym powiedzieć, dlaczego w ogóle ten temat chcemy poruszyć. Przede wszystkim dlatego, że jest ważny, bo my rozmawiamy tylko o ważnych rzeczach. Tylko o ważnych, tak. Wskaza się, tylko. Dobrze, że się tutaj zgadzamy, ale też jest drugi powód, ponieważ ContentOps to jest temat przewodni konferencji SOAP w tym roku, której jesteśmy partnerem po raz kolejny, z czego się niezmiernie cieszymy.

Ale pojawiają się też nowe twarze z Polski, z zagranicy, których nie znamy, ale których chętnie poznamy i dowiemy się, co mają ciekawego do powiedzenia właśnie na temat ContentOps. Michał, chciałem powiedzieć, że jestem pod wrażeniem, jak pamiętasz, w którym odcinku kto był. To jest naprawdę niezła pamięć. Teraz nie wiem, czy powinienem się przyznać, że mam to zapisane, czy że pamiętam. No właśnie nie wiem, przyznasz się, czy się nie przyznasz, bo ja się patrzę na ten sam skrypt, co ty, więc... Dobra, przyznaję się, że miałem to zapisane. Nie pamiętałbym dokładnie, musiałem sobie to znaleźć przedtem. Ale dzięki, że mnie tak wysoko cenisz, że byłbym w stanie to zapamiętać. To teraz może już przejdźmy do samego tematu naszego odcinka. Paweł, ty jesteś ekspertem, więc chciałbym się ciebie zapytać przede wszystkim, co to jest ContentOps?

No to to nie jest DevOps. Jakby w świecie takim bardziej agile'owym DevOps to jest taka sytuacja, który jest cały czas rozwijany i utrzymywany. Jest cały czas testowany i tak dalej. W takim kółeczku to się toczy, że ten software jest dostępny. Na przykład takie coś jak jakiś tam Facebook czy inna aplikacja webowa. Nie ma tak, że czekamy na nową wersję i instalujemy, tylko ona jest cały czas dostępna w jakiejś tam wersji, cały czas są poprawiane rzeczy, naprawiane bugi i tak dalej. To jest ten DevOps. To jest fajnie tak napisane na stronie SOAP-a, gdzie opisuje temat konferencji, czyli ContentOps. Jest napisane, że skoro DevOps pozwala aktualizować oprogramowanie szybciutko, tak w ciągu paru minut, prawda, dosłownie w kwadrans mogę naprawić jakiegoś buga, skoro się ludzie przyzwyczaili do tego, no to oczekują tego samego od innych aspektów, w tym od contentu, prawda, czyli nasze stronki z dokumentacją techniczną powinny też tak samo działać.

Nie wysyłamy klientom erraty, która mówi jak będziesz przeglądał dokumentację to pamiętaj, że tam jest błąd i tu jest poprawka. Tylko po prostu poprawiamy tą dokumentację na bieżąco. Czyli to jest takie z naciskiem na continuous delivery, tak? Tak, dokładnie. Ale żebyśmy nie myśleli, że chodzi tylko o narzędzia, bo w software też nie chodzi tylko o narzędzia. Mówimy tu o procesie, o ludziach, którzy biorą udział i o narzędziach. To są jakby te trzy aspekty tego. I jeszcze trzeba by powiedzieć, że powiedzenie proces, ludzie i narzędzia to jest takie ogromne uogólnienie, bo każda z tych rzeczy ma bardzo wiele aspektów i to nie jest taka kawalkada, że najpierw jest proces, potem są ludzie, potem są narzędzia i to jest ContentOps, tylko w całym ContentOps, które sobie wyobrazimy jak takie kółeczko, nieskończony auroboros, to w każdym momencie są ludzie, procesy i narzędzia, w każdym punkcie na tym okręgu.

Ok, dużo tutaj rzeczy jest napakowanych. Za chwilę sobie tutaj porozmawiamy dokładniej o tym wszystkim, ale wydaje mi się, że w tym całym podejściu Ops, czy to jest DevOps, czy to jest ContentOps, istotne jest też to, że się tak nie izolujemy od siebie jako zespoły. Czyli nie ma takiego jasnego podziału, że dobra, to my robimy feature i teraz odcinamy się, przerzucamy przez ścianę dalej i teraz wy się tym zajmujcie, tak? A oni sobie tam, dobra, to teraz my testujemy, przerzucamy przez ścianę i wrzucamy do zespołu, który publikuje i w ogóle się nie komunikujemy. Wydaje mi się, że kluczowe w tym całym podejściu jest to, że te zespoły ze sobą się mocno integrują, komunikują i współpracują na każdym etapie, że to nie są takie grube krechy odcinające, a dobra, my się tym zajmujemy, już nas nie obchodzi reszta, tylko że to jest właśnie taki ciągły proces, w którym jest software czy tam content

Ale żeby nie było, że sobie tutaj halucynuje jak jakaś sztuczna inteligencja, jeśli chodzi o moje definicje, to znalazłem na stronie Gather Content takie wyjaśnienie, czym jest ContentOps. I teraz uwaga, będę tłumaczył z angielskiego w czasie rzeczywistym, więc przepraszam za wszelkie kalki i kwadratowe stwierdzenia. Czyli Content Operations to są ludzie, proces i technologia, które są wymagane w całej organizacji po to, żeby można było organizować, zarządzać, wytwarzać treść w sposób efektywny, powtarzalny i skalowalny. ContentOps wchodzi do gry po tym, jak zdefiniujemy strategię contentu, a przed tym, jak dostarczamy content do swoich odbiorców. Tak to jest zdefiniowane. Ciekawe, no bo tutaj jakby Content Strategy i Delivery się znalazły poza procesem ContentOps, co moim zdaniem nie musi tak wcale być.

To znaczy, tak może być, jeżeli myślimy o takim cyklu wydawniczym, tak jak na przykład wydawanie książek. Autor napisał książkę, my ją drukujemy i dajemy do księgarni. Wtedy jakby Delivery jest końcem procesu. Natomiast jeżeli utrzymujemy dokumentację do software'u, no to Delivery powinno być częścią tego ContentOps. No i widzisz, i tu już mamy pierwszą kontrowersję. Jak ze wszystkimi nowymi rzeczami, zdarza się, że jest kilka wersji jakiejś tam definicji dla określenia czegoś i tutaj jest tak samo, czyli ContentOps jest zdefiniowane bardzo podobnie przez wiele osób, ale jednak czasami są takie drobne różnice.

ContentOps też ciągle zakłada taką zmienność tego środowiska, czyli jeżeli coś nie działa, to musimy to poprawić. I to dotyczy narzędzi i procesów. Czyli jeżeli mamy proces, który nas ogranicza jakoś, a widzimy, że on nie dobrze działa, no to trzeba go zmienić. Tak samo z narzędziami. Jeżeli coś tam w narzędziach jest niedoautomatyzowane, albo coś się psuje i tak dalej, powinniśmy to zmienić. I wtedy rzeczywiście wartość wszystkiego wzrasta. Użytkownik ma zawsze najnowszą, aktualną treść przed sobą. A nasi ludzie właśnie skupiają się każdy na swoim zadaniu, ale to zadanie jest częścią całości. Wycinamy rzeczy, które nam przeszkadzają, które nam nie służą do osiągnięcia celu. Pamiętam, że miałeś kiedyś taką prezentację, już nie pamiętam dokładnie dla kogo ją robiłeś, ale tam była taka fajna grafika, która do mnie przemawiała.

To był taki znak nieskończoności, na który naniosłeś te wszystkie etapy tego cyklu ContentOps. I to było fajne, bo tak jak wspominałeś na początku, ten proces się nigdy jakby nie kończył. On jakby sobie tak dochodził do pewnego momentu i wracał. I to się wszystko tak kręciło w kółko, to może złe słowo, no bo znak nieskończoności to nie jest kółko, no ale wiesz o co mi chodzi, nie? No pewnie, ale możemy to przedstawić w dowolnym kształcie, na przykład kaczki. No kaczki, wiesz co? A może łabędzia? O, łabędź. Łabądek. Słuchaj, a pamiętasz może, co tam było nad tym wyrysowane dokładnie? Od czego się to zaczynało, przez co przechodziło i dokąd dochodziło i później wracało do którego momentu? Mógłbyś to w jakiś sposób opowiedzieć?

I robimy nową wersję. A tutaj jakby cały czas analizujemy to, jak ta treść jest używana i wyciągamy wnioski. Na podstawie tego jesteśmy w stanie właśnie wrócić do któregokolwiek z etapów tego ContentOps. Niekoniecznie musimy wracać do początku, bo może Content Strategy jest okej, ale na przykład gdzieś tam w środku okazało się, że technicznie coś nie zagrało, czyli nie wiem, nasze szablony są kiepsko zrobione na stronie albo jakieś tam Html5 źle działa, no to na przykład to poprawimy. Ale może się okazać, że ludzie zgłoszą też buga do samej treści, że coś jest źle napisane i trzeba to poprawić. I teraz nie musimy czekać na nowy release, tylko robimy poprawkę, testowanie, znowu publikację i znowu analiza. To wszystko sobie tak fajnie tutaj się kręci. Podoba mi się to podejście. Dorzuciłbym jeszcze tylko analityka.

To jest pasywna analityka, ale też jakiś feedback możemy dostawać. Komentarze u użytkowników, surveje itd. I nie wiem, czy chcemy wskoczyć w taki side topic, ale PDF-y. To jest po prostu zmora, jak dla mnie, takiego ContentOps. No bo to już pomijając aspekty formatowania PDF-ów i pokazywania stron internetowych jako strony książki, No to PDF po prostu będzie czymś przedawnionym, nie? Ktoś sobie pobierze PDF-a, zapisze sobie na laptopie i sobie będzie go otwierał. A tam już są treści nieaktualne. No tak, a z drugiej strony też ktoś może sobie stronę zapisać albo może sobie tą stronę screenshota zrobić i też może sobie to zapamiętać, a może sobie też wyeksportować do PDF-a, jeśli ma taką potrzebę. Może, ale PDF jest zaprojektowane, żeby to zrobić. No tak, tylko że wydaje mi się, że trzeba by tu rozróżnić jakby dwie rzeczy.

Pierwsza to jest PDF dostarczany jakby offline, czyli wysyłasz takiego PDF albo na FTPa go wrzucasz komuś i on sobie tam typowo jest po to, żeby go pobrać. Albo masz coś takiego jak u nas jest, czyli mamy tego PDF-a, ale on jest jakby częścią tego webportalu i to jest jakby jedna z opcji, gdzie przeglądasz sobie online tą dokumentację w formacie HTML, ale możesz sobie ją też pobrać jako PDF. No i dobra, jest ryzyko, że jak ktoś to pobierze, to będzie miał starą wersję, no ale masz jakby narzędzie do tego, że i to miejsce, gdzie możesz aktualizować na bieżąco tego PDF-a. On się aktualizuje w tym samym momencie co HTML. Więc jeśli ktoś przyjdzie na tą stronę, jeszcze raz ten PDF będzie aktualny. Ale wiadomo, nie powstrzymasz człowieka przed tym, żeby go gdzieś tam sobie zapisał i rozsyłał dalej. I zgadzam się, że PDF nie jest optymalnym formatem do tego, żeby ContentOps realizować w sposób pełny i efektywny.

Ale nie o tym była mowa. Tak. Tak. Skupmy się na tym, po co się tu spotkaliśmy, bo nie spotkaliśmy się tutaj dla przyjemności, tylko po to, żeby rozmawiać o poważnych sprawach, Paweł. Dokładnie. Jest to bardzo nieprzyjemna rozmowa. W każdym razie chciałem... Wiesz co, nie wiem właściwie, czy ten side topic nam nie wciąga czegoś nowego do ContentOps, o czym wcześniej nie myślałem, czyli ten nasz użytkownik jest częścią ContentOps. No bo my w pewien sposób sugerujemy jemu zachowanie, jakie ma przejawiać wobec naszej dokumentacji. Jeżeli nasza dokumentacja jest na stronie, no to oczekiwanie nasze jest takie, że on przyjdzie na tę stronę, tę dokumentację oglądać i my mu będziemy serwować aktualną dokumentację, prawda? My sobie tam wymyślamy na przykład, że ona jest wersjonowana, Użytkownik się przełącza na odpowiednią wersję. Możemy mu pokazywać tylko to, co kupił, a nie pokazywać mu, co nie kupił i tak dalej. Jest cały aspekt naszej interakcji z tym użytkownikiem.

No i na przykład takie decyzje, jak dodamy PDF-a. To jest sugestia dla użytkownika, że on powinien tego PDF-a sobie pobrać, prawda? Więc to jest kształtowanie, powiedzmy, oczekiwań naszych wobec użytkownika. I tutaj też warto zauważyć, że w przypadku takiego formatu webowego jest też łatwiej ten feedback zebrać czy analitykę, bo w przypadku PDF-a to nie jest tak łatwo albo wręcz jest to niemożliwe, żeby jakiekolwiek dane automatyczne zbierać od użytkowników, co nam jakby ogranicza możliwości naszego procesu ContentOps. Ale jest jeszcze druga kwestia, że łatwość zgłoszenia problemu przez użytkownika też jest inna niż w przypadku takiej dokumentacji webowej, bo pomyśl sobie w dokumentacji webowej, nie wiem, wrzucasz sobie takie kciuczki w górę i w dół, gdzie możesz łatwo zgłosić, że ten topic był spoko i możesz na przykład kliknąć wyślij komentarz.

No ale my możemy. Tak, ale też dla nich to jest to zachowanie, którego oczekują, prawda? Czyli użytkownik dostaje skończoną dokumentację. To jest dokumentacja do tej wersji urządzenia, ona tak wygląda i to jest to oczekiwanie, które stawiamy przed tym użytkownikiem. Dobra, to wyróżniliśmy w ContentOps takie elementy jak ludzie, proces i narzędzia. Wiesz co Michał, jeszcze mam jedną rzecz. Jest jeszcze jeden taki aspekt, o którym ja na przykład często zapominam, czyli taki jakby koniec życia konkretnej treści, kiedy się chcemy jakoś jej pozbyć. I w to jeszcze też wejdzie może aspekt trochę takiej reorganizacji treści. Jak mamy stronę z dokumentacją, To użytkownik może sobie zapisać swoje jakieś tam ulubione rzeczy, może mieć na przykład linki na swoim wiki dla wszystkich pracowników, żeby trafiali na naszą stronę z dokumentacją w konkretne miejsce.

My na przykład robimy reorganizację. Na przykład dwie role użytkownika się zlepiają w jedną I nie mamy już osobnych stron dla administratora i dla operatora, tylko mamy jedną stronę dla wszystkich. No ale te stare linki, coś by z nimi tam wypadało zrobić. One mogą wszystkie lecieć na 404, albo możemy tam położyć taki wielki baner i powiedzieć, że dokumentacja dla operatora się przeniosła teraz tutaj. To samo możemy robić z rzeczami, które są end of life. Czyli dokumentacja na przykład jest dostępna, ale jest wielki czerwony baner, który mówi, my już nie wspieramy tego feature'a. Albo nie ma już tej dokumentacji, jest tylko wielki czerwony baner. Jeżeli ktoś po prostu ma tą stronę zapisaną, no to tam wchodzi i widzi. I to jest część tego naszego ContentOps, że my mamy też kontrolę nad tym, co się dzieje z treścią, którą wcześniej opublikowaliśmy. Zgadzam się. Dobrze, że o tym wspominasz, bo jest to część, o której się często zapomina.

Odciąć grubą krechą, wykasować stronę i jest 404 i sorry, nie ma? Czy rzeczywiście jakiś tam mechanizm wprowadzić przekierowujący, czy informujący, czy coś podobnego? Tu się jeszcze rodzi jedna sprawa. Jeżeli mamy kilka tych wersji, które utrzymujemy, no to ContentOps nam powinien odpowiedzieć na pytanie, ile czasu poświęcamy której wersji. No bo zawsze publikowanie tej najnowszej i zapominanie o poprzednich, to jest OK, jeśli nasi klienci są na najnowszej wersji, ale jeżeli 30% klientów jest na wersji piątej, 30% na szóstej i 30% na siódmej, no to musimy wszystkie te trzy wersje, jakby musimy im równowagę dać, prawda? Lub musimy dać większą Jakieś tam treści konkretne, na przykład nowszej wersji, bo na niej mamy mało klientów.

Jeżeli ludzie zgłoszą jakieś problemy, to my te rzeczy naprawimy, ale w nowym release'ie. To jest jakby nasza strategia. A potem widzimy, że 80% użytkowników jednak używa poprzedniego release'u produktu i poprzedniego release'u dokumentacji. No to powinniśmy poprawić w poprzednim release'ie, no i oczywiście też w nowym, prawda? Więc to zmienia trochę też naszą strategię tego, jak my to będziemy, jak będziemy te aktualizacje wprowadzać. Ale na szczęście mamy ContentOps i możemy sobie w łatwy sposób zaktualizować poprzednią wersję. W sposób prosty, łatwy i przyjemny. To możemy przejść już do dalszych wątków, czyli ludzie, proces i narzędzia. Chciałbym, żebyś mi powiedział trochę o ludziach. Ludzie. O co chodzi z tymi ludźmi? Kto to jest? Czym się zajmuje? Jakie byś mu tej role wyróżnił? Bo fajnie brzmi cała idea ContentOps, nie?

Ale jak sam widzisz, jest to bardzo skomplikowany temat pod tym kątem, że masz wiele ruchomych części, które ktoś musi ogarnąć. Łatwo się mówi, stwórz sobie środowisko, w którym będziesz w stanie W sposób ciągły, spójny i efektywny dostarczać treść do klientów, ale to się wiąże z tym, że musisz to zaplanować, musisz to napisać, musisz skonfigurować te wszystkie narzędzia, pipeline'y, procesy, musisz wymyślić jakąś strategię. Nawet sama instalacja narzędzi czy utrzymywanie tych narzędzi to już jest spory wydatek czasu i pieniędzy, więc tutaj fajnie by było wyróżnić te role, które mogą być potrzebne w przypadku stworzenia kompleksowo takiego cyklu ContentOps. Ja bym też może powiedział trochę, jak się różni każda rola w ContentOps versus w podejściu bez ContentOps, czy tam jakby takim podejściem mniej ContentOpsowym.

No i ten zarząd jakby ustępuje Miejsca, daje pieniądze na narzędzia, daje pieniądze na szkolenia, dostarcza odpowiednią liczbę ludzi w oparciu o twarde dane i ten ContentOps wtedy się sprawdza jako interfejs do zarządu. Content Strategist jako rola to jest człowiek, który bardzo dużo musi wiedzieć o produkcie, o użytkowniku, I o tym, jak ta treść będzie konsumowana. Niekoniecznie musi znać szczegóły techniczne tego, jak produkt działa, ale musi wiedzieć, po co, co tworzymy i dla kogo, prawda? Więc jest to taka dosyć rozległa, wiedzowa specjalizacja. No i dobrze by było, żeby ten Content Strategist rozumiał procesy, no bo będzie pomagał je współtworzyć. Więc musi też rozumieć te narzędzia i te realia ContentOps. Więc w pewnym sensie ta rola się trochę zmienia, jeżeli dużą rolę odgrywa cały ten cykl ContentOps, czyli te cykliczne procesy i te cyklicznie działające narzędzia Continuous Delivery.

Rola Information Architect. Dostaje jakby taki dodatkowy element powiedzmy takiego równoległego myślenia o zmienianiu rzeczy. Jeżeli dostarczamy na przykład jedną wersję latest and greatest, zawsze tylko jedną, ten Information Architect będzie musiał Reagować na analitykę i update'ować tą treść i tak dalej. Ale jeżeli dostarczamy na przykład wiele wersji i one są wszystkie w tym cyklu ContentOps utrzymywane, no to będzie musiał ten Information Architect się przełączać pomiędzy kontekstami, rozumieć interakcje między wszystkimi wersjami, szukać nowych i lepszych sposobów na przykład przełączania się między wersjami, w sensie dla użytkownika, jak użytkownik ma znaleźć właściwą wersję, jak użytkownikowi pokazać To co potrzebuje i nie za dużo i nie za mało.

Jako taki Tech Writer w takim systemie ContentOps też muszę być bardzo elastyczny, no bo wiem, że moja praca będzie się zmieniać pod wpływem feedbacku i pod wpływem tych wszystkich zmian, które będą zachodzić. No i też pamiętamy o tym, co mówiłeś wcześniej, że nie przerzucamy przez ścianę i nie mówimy nara, tylko cały czas pracujemy i z zespołem developerów, testerów, jakiś tam user experience zespołem, jakiś graphical design i tak dalej, i tak dalej. Więc jest mniejsza szansa na taką pracę w zupełnej izolacji. Bardziej muszę być jakby ekspertem otwartym na otoczenie. Tak mi się przynajmniej wydaje w tym ContentOps. Warto by było jako Tech Writer zainteresować się też analityką, I patrzeć tak jakby z perspektywy takiej bardzo bliskiej na konkretne strony, które napisałem albo moi koledzy napisali, jak one są używane, dlaczego nie są, jaki feedback płynie z tych stron, reagować bezpośrednio na feedback, na przykład ktoś napisał na tej twojej stronie, jest nieaktualna lista jakichś tam logów.

A jeśli chodzi o sam wsad do dania, to wydaje mi się, że tutaj jest jeszcze rola takiego eksperta. I też fajnie byłoby tutaj wspomnieć, czy i w ogóle w jakim wydaniu jest tutaj miejsce dla takiego SME w tym ContentOps, bo my skupiliśmy się na rolach typowo komunikacyjno-technicznych, ale mamy jeszcze ten element ludzi, którzy nam tę treść dostarczają, w sensie ten wsad do treści, czyli wiedzę, jakieś dane źródłowe i to może być programista, to może być product manager, to może być business analyst, To może być ktokolwiek. I teraz, jak jest miejsce dla tej osoby w tym całym ContentOps? Dobrze to opisałeś. Oni dostarczają ten wsad. W naszej metaforze restauracji to jest właśnie rolnik. Rolnik dostarczy plony swojej pracy.

No i przede wszystkim też musisz reagować na potrzeby, czyli jeśli ktoś powie, że ten nóż jest za mały do takiej roboty, no to musisz mu kupić większy i dostarczyć i dbać o to, żeby on działał, czy tam wymyślić jakieś rozwiązanie, które będzie działać. No zgadza się. W świecie contentu, jako ten tool support w ContentOps, to musisz naprawdę mieć szerokie zrozumienie też użytkownika i tego, jak on wchodzi w interakcję. A skąd nabierzesz tego zrozumienia? Właśnie przez przeglądanie analityki. No i narzędzia, które ty dostarczasz ludziom, to są narzędzia do pisania, ale też narzędzia właśnie do analityki i zbierania feedbacku. Czyli oni do ciebie się zwrócą, żeby się zapytać, skąd ja mam wiedzieć, czy ludzie moją stronkę czytają. Więc ty tam setupujesz Google Analytics, czy cokolwiek tam innego się używa.

Setupujesz im jakieś tam dashboardy w Tableau, czy w jakimkolwiek innym narzędziu. Przygotowujesz im jakieś tam narzędzie do surveyów, albo bazę danych komentarzy użytkowników. Tak jak w naszym wypadku te komentarze rootujemy prosto do Jira, gdzie tam jest jakiś proces triażu tych komentarzy. Jest to szeroka specjalizacja. Jakby patrząc z zewnątrz i myśląc sobie o tym, że Tool Support w dokumentacji, no to muszę sprawić, żeby działał Oxygen i potem żeby się generowały z tego stronki PDF-y, no to to jest jakby tylko mały fragment tego wszystkiego. Warto też zaznaczyć, że w przypadku narzędzi to nie jest tak, że jest jedno rozwiązanie czy jedna formuła, która się tutaj sprawdza, bo tak naprawdę ContentOps nie mówi Ci dokładnie tego, że musisz używać modelu Docs as Code, w którym masz Static Site Generator i Markdowna i to wtedy tylko działa, bo to jest takie fajne, lekkie i przyjemne i to sobie możesz tam hulać.