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

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

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.)

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.

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).

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ę?