any2.video vs zatrudnienie autora dokumentacji technicznej: dwie odpowiedzi na ten sam problem z pokryciem
Dobry autor dokumentacji technicznej to jedno z zatrudnień, które dają firmie tworzącej oprogramowanie największy efekt, i nic na tej stronie nie przemawia przeciwko takiej decyzji. Dokumentacja pisana i zweryfikowane wideo odpowiadają na różne połowy problemu z pokryciem, a wybór między nimi to w istocie pytanie o to, która połowa jest obecnie zepsuta.
Czego dowodzi każda z opcji
| Pytanie | Autor dokumentacji technicznej | any2.video |
|---|---|---|
| Co powstaje | Tekst, który można przeszukiwać, linkować i poprawiać. | Nagranie ukończenia zadania oraz instrukcja krok po kroku. |
| Odpowiedź na pytanie „gdzie jest przycisk” | Słowami, które czytelnik musi sam odnieść do ekranu. | Pokazując go. |
| Odpowiedź na pytanie „po co to jest” | Bardzo dobrze. Do tego właśnie służy tekst. | Słabo. Wideo źle radzi sobie z materiałem referencyjnym. |
| Szybkość budowania pokrycia | Szybko w przypadku tekstu, wolno przy wszystkim, co wymaga zrzutów ekranu. | Dwa dni na zadanie, w partiach. |
| Gdzie ludzie to znajdują | Witryna z dokumentacją i wyszukiwarki. | YouTube i asystenci AI, czyli miejsca, w których padają pytania o produkty. |
| Utrzymanie aktualności | Zależy od dyscypliny i procesu przeglądu. | Tag wersji oraz ponowny przebieg przy każdym wydaniu. |
Kiedy autor dokumentacji technicznej jest właściwym wyborem
- Dokumentacja jest niekompletna, sprzeczna lub zaniedbana. Najpierw trzeba to naprawić. Wideo nadbudowane na złej dokumentacji tylko rozpowszechnia błąd.
- Treść ma charakter referencyjny: parametry, interfejsy API, limity, objaśnienia pojęć.
- Czytelnicy muszą wyszukiwać, kopiować i linkować. Nikt nie kopiuje polecenia z wideo.
- Treść musi być częścią procesu wydawniczego, a nie funkcjonować obok niego.
Kiedy nie jest
- Krok jest opisany, a użytkownicy i tak popełniają w nim błąd, co zwykle oznacza, że ekran nie wygląda tak, jak opisuje go zdanie.
- Pytanie brzmi „czy to naprawdę działa”, a tego tekst nie rozstrzygnie, za to dowód na ekranie tak.
- Kupujący wyrabiają sobie opinię na YouTube, gdzie Państwa dokumentacji nie ma.
- Zatrudniony autor spędza tydzień na robieniu zrzutów ekranu zamiast na pisaniu.
Kolejność działań
Najpierw dokumentacja. Jeśli opisana procedura jest błędna, wideo z błędną procedurą to tylko bardziej przekonująca błędna procedura. Z tego powodu odmawialiśmy już zleceń i zrobilibyśmy to znowu.
Gdy dokumentacja jest poprawna, brakuje już nie informacji, lecz dowodu i rozpoznania. Użytkownik, który przeczytał opis kroku i nadal nie może znaleźć przełącznika, nie potrzebuje tego zdania po raz drugi. Potrzebuje zobaczyć ekran.
Do każdego walkthroughu dołączony jest tekst
Dlatego instrukcja krok po kroku i notatki dotyczące rozwiązywania problemów są wliczone w cenę, a nie sprzedawane jako dodatek. Każdy zweryfikowany przebieg daje dokładne kroki, które zadziałały, we właściwej kolejności, razem z nieudanymi próbami i sposobami ich naprawienia. Taki materiał często jest lepszy od tego, co było w dokumentacji, bo powstał na podstawie przebiegu, a nie z pamięci, a zatrudniony u Państwa autor może przenieść go wprost do dokumentacji.
Co zyskuje na tym autor
Robienie zrzutów ekranu to najmniej wartościowa część pracy autora dokumentacji technicznej, a pochłania tydzień jego pracy. Zweryfikowany przebieg daje mu log ze znacznikami czasu, pokazujący, co faktycznie się wydarzyło, czyli surowy materiał, który inaczej musiałby odtwarzać ręcznie.
Pytania
Zatrudnić autora dokumentacji technicznej czy kupić wideo?
Jeśli dokumentacja jest błędna lub jej brakuje, najpierw trzeba zatrudnić autora. Wideo oparte na nieścisłej dokumentacji mnoży błąd. Jeśli dokumentacja jest solidna, a użytkownicy i tak utykają, brakuje dowodu, a nie informacji, i właśnie to zapewnia zweryfikowany walkthrough.
Czy wideo zastępuje naszą dokumentację?
Nie i nie powinno. Tekst można przeszukiwać i kopiować, a jego poprawienie jest tanie. Wideo źle radzi sobie z materiałem referencyjnym, za to dobrze pokazuje ukończenie zadania.
Czy dostajemy coś, z czego skorzysta nasz autor dokumentacji?
Tak. Do każdego walkthroughu dołączone są dokładne kroki, które zadziałały, i nieudane próby, wygenerowane z logu przebiegu. Większość zespołów wkleja je prosto do swojej dokumentacji.
Najszybciej można to rozstrzygnąć na jednym zadaniu wykonanym na oba sposoby. Pierwsze wideo próbne jest bezpłatne.
$ get-sample → $ cd /library