Podręczniki - jak aktualne?

10

Jeśli masz produkt, który istnieje na rynku od dłuższego czasu, ale wciąż jest w fazie aktywnego rozwoju - jak często należy aktualizować podręczniki? Jeśli użytkownicy są stale aktualizowani do najnowszej wersji ze względu na fakt, że organizacja uważa za stosowne, że najnowsze poprawki błędów są zawsze w dostarczonej wersji. Oznacza to, że pewnego dnia możesz naprawić błąd, a następnego dnia zaczyna on pojawiać się w produkcji.

Brian
źródło
1
Czy mówimy o instrukcjach drukowanych czy on-line? Istnieje co najmniej kilka różnych form, które mogą przybierać.
JB King
Podręczniki online (PDF)
Brian

Odpowiedzi:

4

Zaktualizowałbym instrukcję:

  1. Dla każdego ważnego wydania oraz
  2. Gdy ważne nowe funkcje stają się stabilne i na tyle dojrzałe, że wiesz, że nie będą się zmieniać co pięć minut.
Robert Harvey
źródło
3

zaktualizuj instrukcję (PDF) za każdym razem, gdy zmiana kodu zmieni instrukcje w instrukcji - po prostu zaktualizuj instrukcję jako część procesu wydania

jeśli użytkownicy polegają na instrukcji, aby powiedzieć im, jak korzystać z produktu, a produkt się zmienia, to jest zdrowy rozsądek, że odpowiednie sekcje instrukcji również powinny się zmienić

Steven A. Lowe
źródło
1
więc jeśli nie ma piszącego o personelu technicznego, to zaktualizuj go sam?
Brian
@ 0A0D - jeśli nie masz pisarza, nie masz dużego wyboru, chyba że są pracownicy, którzy mogą to zrobić.
JeffO
1
Mam dokument „pliki źródłowe” jako część moich projektów. Są one zawsze aktualizowane w tym samym czasie co kod. Są one wersjonowane z wydaniami i zarządzane przy użyciu tych samych narzędzi do zarządzania źródłami, jak reszta plików projektu (wersja Mercurial!). Mam dość standardowy zestaw instrukcji do projektu i wszystkie są zarządzane w ten sam sposób (instrukcja obsługi, instrukcja konfiguracji / instalacji, informacje o wersji i nasze własne techniczne dokumenty referencyjne / techniczne).
2

Czy w 2010 roku nadal mamy na myśli drukowaną dokumentację? Dlaczego? ;)

Z całą powagą dokumentacja (pomoc aplikacji „F1”, plik PDF lub dokumentacja online) powinna być częścią każdego wydania. Zero wymówek. To takie „publikować”. W rzeczywistości, IMO, nie ma usprawiedliwienia dla braku regularnej aktualizacji dokumentacji (online i PDF), nawet między wydaniami, gdy tylko problemy zostaną poznane i usunięte. Nie potrzebuje tego samego poziomu kontroli jakości - nawet blisko.

Mark Freedman
źródło
2

Zakładam, że mówisz o dokumentacji użytkownika końcowego. Pisanie dokumentacji jest uciążliwe w @ $$ i chociaż opracowałem jakąś technikę, aby mnie przekonać, że jest odwrotnie, nadal mam z tym problemy. Oto jak próbuję to zarządzać:

Zintegruj aktualizację dokumentacji z DoD ( Definicja ukończenia )

Zapewni to, że twoja dokumentacja będzie aktualna po zakończeniu każdego opowiadania użytkownika.

Oto definicja gotowego, którą napisaliśmy. Próbowałem zachować oryginalne formatowanie, więc masz pomysł. To strona A4 umieszczona na tablicy.

---------- 8 <------------ Wytnij tutaj ------------ 8 <----------

Nie podlega negocjacji

Definicja „Gotowe”

  • Kod z 80% pokryciem testu jednostkowego, zatwierdzony w repozytorium

  • Zrzuty ekranu, jeśli dotyczy (1024 x 728, 395 x 281, 170 x 121 i 729 x 329)

  • Opisy funkcji, jeśli dotyczy (50 znaków, 100 znaków)

  • Pełna dokumentacja użytkownika końcowego

  • Nowy plik poprawnie zaktualizowany

---------- 8 <------------ Wytnij tutaj ------------ 8 <----------

Oczywiście możesz dodać proces recenzji do dokumentacji. Mamy to, ponieważ nikt z nas nie mówi w języku angielskim.

Jedną z zalet takiej Definicji Gotowości jest to, że twój produkt jest potencjalnie wysyłany na końcu każdego ukończenia historii użytkownika.

Użyj tej techniki w połączeniu z .


źródło
1

W mojej organizacji zazwyczaj mamy 3 rodzaje wydań:

  1. Wersja inżynierska - zasadniczo poprawka dla określonego klienta lub funkcji, o którą tylko konkretny klient poprosił natychmiast.
  2. Drobne wydanie - poprawki błędów, wsparcie przyrostowe
  3. Major Release - obsługa nowych funkcji itp.

Z definicji wersja główna musi mieć odpowiednią dokumentację zarówno w trybie online, jak i offline. Nasz system śledzenia zapewnia, że ​​dokumentacja jest w dużej mierze częścią listy kontrolnej.

Drobne wydania wymagają dokumentacji tylko na temat wszystkiego, co zostało dodane na poziomie postrzegania użytkownika. Jeśli więc włączyłeś kolejną heurystykę, która może zmniejszyć złożoność czasu w niektórych konkretnych scenariuszach, może to być znaczące wezwanie do umieszczenia go w pliku pdf.

Wydania inżynieryjne mogłyby obejść się bez dokumentacji. Niektóre nieformalne uwagi dotyczące użytkowania powinny być wystarczająco dobre, aby zacząć.

Fanatyk 23
źródło
0

Dokumentacja powinna być zsynchronizowana z dowolnym oprogramowaniem wysyłanym do klienta. Każde inne niedopasowanie spowoduje problemy. A jeśli nie masz pisarza na personelu, spróbuj kontrahentów. Gdy znajdziesz taki, który ci się podoba, nie zatrzymuj go.

SnoopDougieDoug
źródło