Wybór odpowiednich wskaźników dla projektu

Ten przewodnik ma pomóc organizacjom zrozumieć, jakie problemy można rozwiązać dzięki lepszej dokumentacji, oraz jak wybrać odpowiednie wskaźniki do projektów dokumentacji.

Obecny etap:
program Dokumenty na sezon 2021 zakończył się 14 grudnia 2021 r. Zobacz oś czasu.

Opisz, na czym polega problem

Zanim zaczniesz wybierać dane, upewnij się, że dobrze znasz problem, który próbujesz rozwiązać. Podaj jak najwięcej szczegółów.

  • „Prośby o pull request dotyczące dokumentacji dotyczącej rejestracji zajmują zbyt dużo czasu na połączenie. Uczestnicy rezygnują i odchodzą”.
  • „Zobaczmy zbyt wiele zgłoszonych problemów, aby pomóc w rozszyfrowaniu kodów błędów”.
  • „Nasz potok CI/CD jest niestabilny. Zbyt wiele testów kończy się niepowodzeniem z nieznanych powodów”.
  • „Na naszych cotygodniowych spotkaniach ludzie wydają się być marudni”.

Sformułuj hipotezę

Poszukaj przyczyn i skutków. Co może być przyczyną opisanego problemu? Pamiętaj, że problemy mogą mieć wiele przyczyn lub ich przyczyny mogą się nakładać.

  • „Scalanie żądań pull na potrzeby dokumentacji wprowadzającej zajmuje bardzo dużo czasu, ponieważ nie mamy jasnych wytycznych dotyczących stylu. Recenzenci albo odkładają sprawdzenie PR, ponieważ nie wiedzą, co zrobić, albo wielokrotnie odwołują się do współtwórców w sprawie formatowania.
  • „Użytkownicy muszą zgłaszać problemy, ponieważ nie mogą znaleźć informacji o kodach błędów w dokumentacji”.
  • „Nasze testy CI/CD się nie udają, ponieważ napotykamy ograniczenia planu i limity czasu u naszego dostawcy”.
  • „Na naszych cotygodniowych spotkaniach ludzie są źli, ponieważ odbywają się one o 5:30 rano w ich strefie czasowej”.

Proponowanie rozwiązania

Czy problem można rozwiązać, wprowadzając nową lub lepszą dokumentację?

  • „Gdyby mieliśmy wskazówki stylistyczne, koordynatorzy mogliby je sprawdzić przed przesłaniem swoich PR. Weryfikatorzy wiedzieli, co sprawdzić. Weryfikatorzy i współtwórcy nie będą musieli spierać się o format, ton i styl”.
  • „Gdybyśmy mieli dokumentację kodów błędów, użytkownicy mogliby znaleźć odpowiedzi w niej, zamiast zgłaszać problemy”.
  • „Wydaje mi się, że lepsza dokumentacja nie rozwiązuje naszego problemu CI/CD”.
  • „Możemy zacząć każde spotkanie od żartu. Stworzenie zbioru żartów typu „pukanie, pukanie” pomoże nam rozpocząć spotkania z uśmiechem”.

Skoncentruj się na konkretach

Czy potrafisz określić, na czym polega problem?

  • „Co tak naprawdę oznacza „łączenie PR trwa zbyt długo”? Dwa miesiące? Dwa tygodnie? Jak długo autorzy będą czekać na sprawdzenie, zanim się poddadzą?
  • „Ile problemów związanych z kodami błędów jest „zbyt dużą liczbą problemów”?
  • „Hmm… jak bardzo „zbyt zły”?

Sprawdzanie wymierności

Jak sprawdzić zaproponowane dane? Czy można ją łatwo i dokładnie zmierzyć? Czy pomiar zależy od tego, kto go przeprowadza?

  • „Możemy łatwo sprawdzić, jak długo trwa prośba o przechwycenie i jak długo minęło od momentu, gdy poproszono o sprawdzenie. Nie jesteśmy w stanie dokładnie zmierzyć, kiedy dany użytkownik rezygnuje”.
  • „Możemy policzyć, ile problemów ma tag „error-code” (kod błędu), lub przeszukać problemy pod kątem kodu błędu”.
  • „Nie możemy w dobry sposób zmierzyć niezadowolenia użytkowników”.

Dodaj dodatkowe dane

Czy istnieją inne dane, które pomogą Ci ustalić, czy dokumentacja rozwiązuje Twój problem? Czy dane docelowe są zawsze takie same?

  • „Dłuższe PR wymagają więcej czasu na sprawdzenie. Powinniśmy mieć różne progi dla różnych rozmiarów PR. Chcemy zmierzyć czas potrzebny na scalenie w przypadku małych, średnich, dużych i gigantycznych PR-ów.
  • „Możemy sprawdzić, ile razy została wyświetlona dokumentacja dotycząca kodów błędów, i sprawdzić, czy liczba ta koreluje z mniejszą liczbą zgłaszanych problemów”.

Wybierz przedział czasu

  • „Uważamy, że 2 tygodnie to rozsądny czas na połączenie małych i średnich PR-ów, a wszystkie PR-y powinny zostać połączone w ciągu miesiąca. Będziemy więc mierzyć co 2 tygodnie”.
  • „Nie ma sensu codziennie aktualizować liczby problemów związanych z kodami błędów, ponieważ zwykle zajmuje nam to tydzień. Będziemy to mierzyć co tydzień”.

Zapisz cele

Jaka zmiana wybranego rodzaju danych musiałaby nastąpić, aby można było uznać projekt za udany? Warto wyznaczyć ilościowe cele dotyczące wybranych danych.

  • „Gdybyśmy osiągnęli nasz cel, czyli zamknąć każdy nowy projekt PR w mniej niż miesiąc, byłby to sukces. Gdyby średni czas zamykania dużych spraw PR skrócił się o 2 tygodnie, byłby to ogromny sukces”.
  • „W idealnej sytuacji nie zobaczylibyśmy nowych problemów związanych z błędami. Uważamy jednak, że projekt był udany, jeśli liczba zgłoszonych problemów związanych z błędami spadła o 50%”.