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
Odpowiedzi:
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ąć.
źródło
Tak najbardziej zdecydowanie ALE:
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.
źródło
Preferuj wskazywanie na dokumentację offline dołączoną do biblioteki, a nie online.
(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ć tylkohttps
. Lub wszyscy moglibyśmy wrócić dogopher
protokoł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).
źródło
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ę?
źródło