Często rozwiązuję błędy, znajdując odpowiedź na temat Przepełnienia stosu. Czy złym zwyczajem jest dodawanie fragmentu, dlaczego zrobiłem to, co zrobiłem, a następnie dodawanie łącza do artykułu lub strony z Internetu?
Często rozwiązuję błędy, znajdując odpowiedź na temat Przepełnienia stosu. Czy złym zwyczajem jest dodawanie fragmentu, dlaczego zrobiłem to, co zrobiłem, a następnie dodawanie łącza do artykułu lub strony z Internetu?
Odpowiedzi:
Nie sądzę, że jest źle, ale linki zewnętrzne mają zły nawyk rezygnacji z cyklu życia rozwiązania. Robiąc to, zalecam umieszczenie wystarczającego podsumowania, które pomoże czytelnikowi, jeśli link przestanie działać.
Dlatego firmy powinny mieć własne repozytorium wiedzy. Na przykład moja firma ma korporacyjną firmę Redmine, która służy do zarządzania projektem, sprzedaży biletów (śledzenia błędów i zadań) oraz narzędzia, z którego najczęściej korzystam - wiki . Wszystkie te funkcje dla jednego projektu :-)
Co mamy na wiki projektu?
Umieściłem bibliografię (linki) na Misc wiki. Ale tylko od tych, którym ufam:
Moja bibliografia zawiera spisane przeze mnie streszczenie, aby upewnić się, że rozumiem, do czego linkuję. Staram się zachować jasność Javadoc. Każdy link w kodzie odnosi się do wiki Redmine lub kodu problemu Redmine.
Wobec braku narzędzi takich jak Redmine, okazało się, że pliki Markdown są przydatne do tych celów. Ogólnie dla programistów ze względu na te pliki znajdują się w SCM i są dostarczane wraz z kodem.
Łącza do sieci są nieco problematyczne jako dokumentacja, ponieważ Internet nie gwarantuje, że zawartość, którą widzisz za nimi, będzie taka sama, jak zobaczysz przyszły czytnik dokumentów. Jeśli to możliwe, staraj się łączyć tylko z zasobami, których zmiana jest mało prawdopodobna.
Na przykład, kiedy łączysz się z Wikipedią, powinieneś wyraźnie połączyć się z dzisiejszą wersją zamiast ogólnej nazwy artykułu. W przypadku stackexchange.com w tej chwili wydaje się mało prawdopodobne, aby zniknęło, ale pytania są edytowane lub nawet usuwane przez cały czas, a za pięć lat może pojawić się nowy gorący punkt spotkań. Nie zaryzykowałbym powieszenia dokumentacji, która niesie ze sobą znaczną wartość biznesową na stronie tak zewnętrznej dla twojej organizacji.