Zamieść link do odpowiedniej dokumentacji w komunikacie o błędzie?

10

Tworzymy komercyjną bibliotekę i przykłady kodu, które są używane przez zewnętrznych programistów. Mamy (zamkniętą, dostępną dla zarejestrowanych użytkowników) dokumentację, która szczegółowo wyjaśnia, jak korzystać z biblioteki.

Wielu programistów jest użytkownikami po raz pierwszy, więc napotyka się na wiele podstawowych błędów.

Czy właściwe jest umieszczenie łączy do dokumentacji w dzienniku błędów? Jakie są możliwe wady? Mogę przewidzieć kilka, ale wydaje się, że można pokonać następujące

  • Adres URL dokumentacji jest nieaktualny
  • Błędy specyficzne dla wersji, które nie są odzwierciedlone w najnowszej dokumentacji
  • Coś jeszcze jest nie tak i marnujemy czas programisty, wysyłając go do nieistotnego dokumentu

Czy pod przykładem tego, co mam na myśli, warto dodać pogrubiony tekst?

[BŁĄD] Nie udało się wykonać celu org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: generowanie (default-cli) w projekcie autonomicznym-pom: Pożądany archetyp nie istnieje (com.example.library. archetypes: library-archetype-blank: 1.2.3.0) -> Proszę zobaczyć http://example.com/docs/setting-up-an-archetype, aby uzyskać więcej informacji i możliwe rozwiązywanie problemów

Von Lion
źródło
5
Imo, błędy opisowe są dobre, a ci oferujący pomoc jeszcze lepiej.
Cees Timmerman
@CeesTimmerman W pełni się zgadzam, ale nie spotkałem się z tego typu wiadomościami. To sprawia, że ​​waham się, czy zacząć to robić, ponieważ prawdopodobnie jest to dobry powód ..
Von Lion
Widziałem je na 404 stronach i w oprogramowaniu, którego nie pamiętam, może Homebrew.
Cees Timmerman
1
Jedną dodatkową rzeczą do rozważenia jest to, jak prawdopodobne jest, że informacja o błędzie, którą odsyłasz, jest widziana przez człowieka (i nie jest interpretowana przez oprogramowanie klienckie do przekształcenia w komunikat przyjazny dla użytkownika).
Bart van Ingen Schenau
3
@VonLion: Robienie rzeczy tylko dlatego, że wszyscy inni to robią, jest receptą na przeciętność.
Robert Harvey

Odpowiedzi:

8

Zgodnie z tymi wytycznymi dotyczącymi komunikatów o błędach i moim doświadczeniem ludzie lubią oszczędzać czas, nie czytając dokumentacji lub pomocy. Błąd Google może być również poza nimi, więc dołącz link, gdy mają powód, aby go kliknąć.

Wreszcie, prawdopodobnie znasz już Pierwsze Prawo Dokumentacji Komputerowej Nielsena: ludzie go nie czytają. To odkrycie jest jeszcze silniejsze w przypadku stron internetowych, na których użytkownicy naprawdę unikają czytania, które nie jest niezbędne do ich zadania. Kliknij Pomoc? Nigdy.

Użytkownicy czytają dokumentację systemu tylko wtedy, gdy mają kłopoty (to drugie prawo). Są szczególnie uważni, gdy chcą naprawić błąd. Biorąc to pod uwagę, możesz wykorzystać komunikaty o błędach jako zasoby edukacyjne, aby przekazać użytkownikom niewielką ilość wiedzy. Oczywiście komunikaty o błędach powinny być krótkie i na temat, tak jak cała zawartość sieci. Jednak komunikaty o błędach mogą nadal uczyć użytkowników trochę o tym, jak działa system i dostarczać im informacji, których potrzebują, aby lepiej go używać. Aby osiągnąć ten cel, podstawowa technologia sieci umożliwia kolejną wytyczną:

Łącza hipertekstowe mogą być użyte do połączenia zwięzłego komunikatu o błędzie ze stroną z dodatkowym materiałem w tle lub wyjaśnieniem problemu. (Nie przesadzaj jednak.)

Cees Timmerman
źródło
Dziękuję Ci za to! Jest jednak trochę stary, rok 2001 był zanim naprawdę zrozumieliśmy całą tę „internetową” rzecz :-)
Von Lion
3
To wciąż dobra rada, ale być może ten ostatni tweet Johna Carmacka pomaga.
Cees Timmerman
6

Tak najbardziej zdecydowanie ALE:

  • Problemem będzie zgnilizna linków. Idealnie wygeneruj link dynamicznie ze znanego dokumentu docelowego, ale uzyskaj prefiks z jakiejś formy konfiguracji. Jeśli serwer się zmieni, możesz zachować starszy kod, aktualizując ten element konfiguracji. Możesz także udostępnić dokument lokalnie, zmieniając tę ​​konfigurację prefiksu.
  • Wersjonowanie : W tym samym duchu, jeśli możesz, włącz wersjonowanie do linku w pewnej pojemności, tak aby link zawsze wskazywał poprawną wersję dokumentacji.
  • Udostępnij dokument jako edytowalny Coś w rodzaju strony typu wiki dla twojej dokumentacji, w której możesz dynamicznie poprawiać błędy, idealnie również pozwalając użytkownikom na komentowanie bezpośrednio na stronie. dzięki temu użytkownicy będą mogli łatwiej uczestniczyć i znaleźć to, czego potrzebują, a otrzymasz złote informacje, aby utrzymać dokument w dobrym stanie, ale upewnij się, że regularnie go monitorujesz, a przede wszystkim aktywnie uczestniczysz .
  • W wygenerowanych szablonach system kompilacji generuje podstawowy szablon dokumentacji bezpośrednio z adnotacji w kodzie. Uprość to, ale zapewni to, że każdy link zawsze wskazuje na prawidłową dokumentację. Jeśli korzystasz z wiki, upewnij się, że możesz łatwo przesuwać te szablony i upewnij się, że możesz promować stronę z dokumentacją w taki sam sposób, jak robisz to dla swojego kodu (masz witrynę deweloperską inną niż strona producenta i promowanie kodu do prod będzie wykonaj wstawki w witrynie prod automatycznie).

Jeśli tworzysz w Javie lub .NET, dokument może być zawarty w pliku jar lub DLL, a zmieniając prefiks, kod może pobrać go lokalnie.

Jeśli wybierzesz podejście wiki, gorąco polecam DokuWiki ze względu na jego prostotę i fakt, że jest on oparty na płaskich plikach tekstowych, co czyni go bardzo przyjaznym do automatycznego wstrzykiwania z systemu kompilacji. To powiedziawszy, nie wiem wystarczająco dużo o twoim środowisku lub klientach, aby naprawdę wiedzieć, czy to będzie dobrze pasujące YMMV.

Niektóre z najbardziej udanych narzędzi, które stworzyłem, przyjęły podobne podejście, w którym komunikat o błędzie był skierowany do faktycznego użytkownika, który najprawdopodobniej wykonałby zadanie. Oznaczało to, że musiałem zrobić wiele wyjątków, łapiąc i owijając, aby upewnić się, że błąd jest na odpowiednim poziomie abstrakcji. Upewniłem się również, że każdy komunikat o błędzie będzie zawierał najbardziej prawdopodobne źródła błędów i wskazuje na potencjalne rozwiązania „Czy zapomniałeś ustawić wartość konfiguracji xxxx?”, „Upewnij się, że xxx i yyy nie powodują konfliktu, nadając im różne nazwy” itp. Gdzie XXX i tak dalej zostanie wygenerowany z kontekstu, w którym wystąpił błąd.

To podejście było nieco prostsze, ale także bardziej ograniczone. Miał jednak wadę, że dokumentacja będzie zawsze obecna, gdy zajdzie taka potrzeba, brak możliwości zepsucia łącza.

Twoje podejście jest następną ewolucją. Znacznie bardziej skomplikowany, ale ma również znacznie więcej potencjalnych zysków. Będzie to jednak kosztowne, ale jeśli zrobione dobrze, łatwo się zwróci.

Newtopian
źródło
Dziękuję za tę obszerną odpowiedź! Zgnilizna łącza z pewnością będzie problemem, ale mam nadzieję, że czujność przy monitorowaniu 404 będzie wystarczająca; zespół deweloperów na pewno będzie wymagał dużo wysiłku i wysiłku (jest to istniejąca baza kodów ... byłoby łatwe do wprowadzenia, gdyby była nowa), ale jak mówisz, korzyści mogą być tego warte!
von Lion
+1 za komentarze do dokumentacji .
Cees Timmerman
5

Preferuj wskazywanie na dokumentację offline dołączoną do biblioteki, a nie online.

(com.example.library.archetypes: biblioteka-archetype-blank: 1.2.3.0) -> Proszę zobaczyć /usr/share/myprog-3.8.1/docs/setting-up-an-archetype, aby uzyskać więcej informacji i możliwe rozwiązywanie problemów

(oczywiście jeśli jest to biblioteka systemu Windows, ścieżka byłaby inna).

Korzyści tutaj:

  • W ten sposób dokumentacja jest zawsze zsynchronizowana z biblioteką. Ludzie rozwijają i rozwiązują problemy ze starymi wersjami bibliotek. Twoja firma może zmienić nazwę, zmienić nazwę produktu lub ktoś może upuścić piłkę przy odnawianiu example.com.

  • Sieć zmienia się szybko. Podany przez Ciebie link jest http, ale za kilka lat jego prawdopodobne główne przeglądarki będą obsługiwać tylko https. Lub wszyscy moglibyśmy wrócić do gopherprotokołu.

  • Rozwiązywanie problemów z aplikacjami nie zawsze występuje w środowisku z dostępem do Internetu (lub przynajmniej bezpośrednim dostępem do Twojej domeny).

  • Wspominasz, że twoja dokumentacja znajduje się za ścianą „uwierzytelniania”. Konieczność utworzenia konta w witrynie tylko po to, by zrozumieć komunikat o błędzie, nie jest przyjemna (dlatego SO nie wymaga logowania).

dlasalle
źródło
3

Istnieje naprawdę skuteczny sposób na rozwiązanie tego problemu. Upewnij się, że wyjątek w połączeniu z wiadomością jest na tyle unikalny, że wklejenie go do wyszukiwania w sieci pozwala łatwo znaleźć wszystkie odpowiednie wpisy dotyczące dokładnie tego problemu.

To jest sekretny powód, dla którego tak bardzo nienawidzę wyjątków wskaźnika zerowego. Pewnie nienawidzę, że musimy nawet sprawdzać, czy nie ma wartości zerowej, ale najbardziej martwi mnie to, że kiedy trafiam na jeden, jedynym naprawdę unikalnym identyfikatorem, którego muszę szukać, jest zmienna liczba linii.

Tak, chciałbym móc ich szukać. Och, jasne, wiem, że tak się stało, ponieważ coś zostało pozostawione puste, a następnie wykorzystane. To, co nie zawsze jest od razu oczywiste, to DLACZEGO coś zostało puste.

Więc pewnie, weź pod uwagę wszystkie inne rozwiązania dotyczące dokumentacji. Ale najbardziej leniwe, co możesz zrobić, że zrobi mi to najlepiej, to po prostu daj mi coś, co mogę zrobić w Google.

Pięknie proszę?

candied_orange
źródło
Możesz spróbować wyszukać plik i numer linii w searchcode.com
Cees Timmerman