Jak sobie radzić z recenzją merytoryczną dokumentacji?

Dokumentacja, która jest dokładna pod względem merytorycznym to sprawdzone źródło informacji o produkcie, które podnosi wiarygodność Twojej firmy. Nieaktualne informacje mogą wpłynąć niekorzystnie na tempo rozwoju produktu oraz na klientów, którzy nie będą w stanie rozwiązać swoich problemów sięgając po dokumentację. Nieścisłości napotkane w dokumentacji wydłużają również czas potrzebny do opanowania produktu.

Portal TechRepublic w jednym z artykułów daje nam wskazówki jak radzić sobie z recenzją merytoryczną dokumentacji. Poniżej przedstawiamy naszą „skondensowaną” wersję 🙂

Stwórz listę kontrolną

Wielu programistów i kierowników nie ma doświadczenia w sprawdzaniu dokumentacji pod kątem merytorycznym. Poniższe punkty warto zawrzeć w liście kontrolnej, żeby sprawdzający wiedzieli co mają robić:

  • Skup się na tym czy technologia działa tak jak jest to opisane. To nie jest recenzja edytorska.
  • Sprawdź dokładność wszystkich opisanych kroków.
  • Sprawdź dokładnośc wszystkich zrzutów ekranu.

Zbuduj poczucie odpowiedzialności

Jednym z powodów dla których recenzje merytoryczne są lekceważone jest brak poczucia odpowiedzialności. Takie poczucie można zbudować w następujący sposób:

  • Dodaj do dokumentu imię i nazwisko autora oraz recenzenta, chyba że polityka firmy tego zabrania.
  • Dodaj recenzje merytoryczne do obowiązków programistów, z których są rozliczani w ramach rozmów rocznych.
  • Przypisz konkretne osoby do recenzji dokumentacji w trakcie planowania projektu.

Podnieś poprzeczkę dokumentalistom

Ile firm, tyle definicji zawodu Technical Writera. Nie zmienia to jednak faktu, że osoby piastujące takie stanowisko muszą mieć swój udział w dokładności merytorycznej dokumentacji, którą tworzą.

Kierownicy powinni określić odpowiednio wysoki poziom wiedzy technicznej, którego wymagają od dokumentalistów. Na pewno nie wszyscy będą z tego zadowoleni, jednak podniesienie tego poziomu to korzyść dla wszystkich. Jeśli dokumentaliści nie będą w stanie spełnić wyższych standardów, konieczne może być zweryfikowanie roli dokumentalisty w odniesieniu do strategii firmy i oczekiwań klientów.

Podniesienie poprzeczki dla dokumentalistów to nie koniec. Kolejnym krokiem jest umożliwienie im spełnienia nowych wymagań, dlatego trzeba im dać lepszy dostęp do technologii, którą opisują:

  • Włącz dokumentalistów w spotkania dotyczące projektowania i rozwoju produktu.
  • Włącz dokumentalistów w proces rozwoju wymagań technicznych, specyfikacji funkcjonalnych i dokumentów projektowych.
  • Dopisz ich do list mailingowych dla programistów.
  • Daj im dostęp do wewnętrznych wersji produktu, które są tworzone w trakcie jego rozwoju. Bezpośredni kontakt z produktem pozwala zwalczać izolację dokumentalisty i może dostarczyć nowego punktu widzenia, którego nie posiadają programiści i kierownicy projektu.
  • Zachęcaj dokumentalistów do zaznajamiania się z technologią, na której zbudowany jest produkt. Na przykład, jeśli firma rozwija aplikacje oparte na Javie, zachęcaj dokumentalistów do poszerzania wiedzy na temat programowania w tym języku.

Określ priorytety dla kluczowych programistów

Zazwyczaj w stadzie programistów znajduje się jakiś „osobnik alfa”, który posiada obszerną wiedzę na temat całego projektu, ale ma na głowie sporo rzeczy, przez co wiecznie nie ma czasu. Pomimo tego, że jego grafik jest napięty, wiedza którą posiada jest niezbędna z punktu widzenia dokładności dokumentacji. Poniżej lista wskazówek jak wyegzekwować recenzcję merytoryczną od takich ekspertów:

  • Nie łudź się, że taki ekspert sprawdzi dokument od deski do deski.
  • Współpracuj z dokumentalistami z celu określenia sekcji dokumentu, które muszą koniecznie zostać sprawdzone przez eksperta.
  • Współpracuj z ekspertami i ich kierownictwem w celu ustalenia dogodnych momentów do sprawdzenia dokumentacji, podczas których nikt nie będzie przeszkadzał.
  • Dostarcz eskpertowi konkretną listę tego co musi sprawdzić. Zapewnij ich, że reszta zespołu sprawdza pozostałe części dokumentu i że ich wkład jest niezbędny w przypadku sekcji dokumentu, które związane są z tym w czym się specjalizują.

Dokładna recenzja merytoryczna dokumentacji to zysk zarówno dla firmy jak i klientów. Dla ekspertów technicznych jest to zazwyczaj przykry obowiązek, a dla kierowników nie lada wyzwanie, żeby określić priorytety w odpowiedni sposób. Jednak przy odpowiednim planowaniu i współpracy między zespołami na pewno jesteśmy w stanie osiągnąć jakiś kompromis, dzięki któremu jakość naszej dokumentacji będzie coraz wyższa.