Co dokładnie obejmuje „dokumentację”?

Kiedy mówimy „dokumentacja” dla oprogramowania, co to obejmuje, a czego nie powinno to obejmować?

Na przykład ostatnie pytanie, czy komentarze są uważane za dokumentację?

Ale jest wiele innych dziedzin, dla których jest to również ważne pytanie, niektóre bardziej oczywiste niż inne:

• Instrukcje (oczywiście)
• Informacje o wydaniu?
• Poradniki
• Komentarze
• Ktoś jeszcze?

Gdzie jest narysowana linia. Na przykład, jeśli „samouczek” jest dokumentacją, czy jest to dokumentacja samouczka wideo, czy może jest to coś innego?

Zasadniczo coś w oprogramowaniu nie jest „wykonywane”, dopóki nie zostanie zaimplementowane, przetestowane i udokumentowane. Stąd pytanie, jakie rzeczy powinniśmy rozważyć w ramach dokumentacji, aby rozważyć coś „zrobionego”.

_{Pytanie inspiruje nas z ostatnich opinii klientów na naszej konferencji wskazujących, że nasz doktor potrzebował więcej „próbek”, których wcześniej nie byliśmy tak dobrzy w rozpatrywaniu, jak powinniśmy.}

_{Odbiorcy: programiści korzystający z naszej bazy danych, języków programowania i powiązanych narzędzi (np. Klienci administracyjni do wspomnianej bazy danych)}

Celem dokumentacji jest opisanie i wyjaśnienie oprogramowania, aby można było zdefiniować dokumentację jako zbiór artefaktów, które przyczyniają się do tego opisu lub objaśnienia. Prawdopodobnie nie uwzględniłbyś powiązanych działań jako części dokumentacji: np. Tygodniowy kurs szkoleniowy nie jest dokumentacją, ale materiałami kursu są; pięciominutowy czat na tablicy nie jest dokumentacją, ale obrazem tablicy.

Mając na uwadze cel (objaśnienie oprogramowania), dokumentacja jest ukończona, gdy klient jest zadowolony z wyjaśnienia : tak jak oprogramowanie jest ukończone, gdy klient jest zadowolony z oprogramowania. Pamiętaj, że klient dokumentacji nie zawsze jest tym samym, co klient płacący za oprogramowanie: personel pomocniczy, testerzy, handlowcy i inni będą potrzebować pewnej wiedzy na temat działania oprogramowania i jego działania.

Pomaga to zrozumieć, gdzie leży twoja granica dla tego, co powinno być zawarte w dokumentacji. Używając „czytnika” jako wygodnego skrótu, choć akceptujemy, że można dołączyć wideo lub audio: wszystko, co pomaga czytelnikowi uzyskać potrzebne informacje na temat oprogramowania, to dokumentacja, której mogą używać, a wszystko inne nie. Jeśli klient potrzebuje szczegółowych instrukcji dotyczących wszystkich przypadków użycia, musi to stanowić część dokumentacji. Twoi programiści prawdopodobnie potrzebują kodu źródłowego, informacji o repozytorium kontroli wersji i instrukcji budowania: to jest dla nich dokumentacja, ale jak opisano powyżej, nie byłaby częścią dokumentacji klienta.

Myślę, że zabrałeś niewłaściwą część swojej rozmowy na konferencji. Nowoczesne metodologie tworzenia oprogramowania zalecają, aby zespół programistów ściśle współpracował z klientami (lub właścicielem produktu, który działa jako proxy klienta). W przypadku wszystkich dostarczonych prac definicja „wykonanego” jest czymś, co jest negocjowane między zespołem a jego klientem i jest powtarzane w miarę opracowywania oprogramowania.

Problem, na który natrafiłeś, polegał na tym, że rozróżniasz między tym, co zakładasz, że klient potrzebuje, a tym, czego oczekuje od ciebie, więc na koniec niespodzianka „hej, gdzie są wszystkie próbki”.

O ile chodzi o dokumentację ... cóż, to prawie wszystko, co wymieniłeś, a może jeszcze kilka rzeczy, których nie zrobiłeś. Ale nikt nie może ci powiedzieć, ile dokumentacji potrzebuje twój projekt. Każdy projekt jest inny i od zespołu, właściciela produktu i klientów zależy określenie poziomu i rodzaju dokumentacji wymaganej dla projektu.

Niektóre czynniki, które mogłyby wejść w grę:

• Czy tworzysz oprogramowanie wer. 1.0, a oni przechodzą do innych projektów, czy jest to projekt długoterminowy? Komentarze / dokumenty projektowe stają się znacznie ważniejsze w tym drugim przypadku. Z drugiej strony, jeśli twoim klientem jest sklep z pączkami dla mam i pop, a ty piszesz dla nich stronę internetową, której nigdy nie zobaczysz ... myślę, że dokumentacja kodu jest dobra, ale nie tak ważna.
• Czy opracowujesz grę mobilną lub oprogramowanie kontrolujące czujnik tętna w szpitalu? Zgadnij, która będzie miała definicję „zrobione”, która zawiera znacznie więcej dokumentacji?
• Czy Twoi klienci są typowymi użytkownikami końcowymi, czy też są innymi programistami? Czy udostępniasz interfejs API / SDK, który udostępniasz?
• Jaki jest poziom wiedzy specjalistycznej Twoich klientów? Wpływa to na wybór samouczka wideo a materiału pisemnego vs. pewnego rodzaju interaktywnej aplikacji samouczka
• Czy Twoim klientom zależy na tym, co zmieniło się z wersji na wersję. Niektórzy. Większość nie. Dla nielicznych to prawo (lub blisko tego) się troszczyć.

Dokumentacja jest materiałem przeznaczonym do czytania bez modyfikacji.

Myślę, że nie można pomylić się z definicją opartą na celu ... ale tylko wtedy, gdy poprawnie zdefiniujesz cel.

• ^{Prawidłowe zdefiniowanie celu dokumentacji nie jest dość proste. Bezpośrednie (naiwne, jeśli chcesz) rozróżnienie, które naturalnie przychodzi na myśl, polega na tym, że dokumentacja jest wszystkim, co jest przeznaczone do czytania - podczas gdy dla porównania, kod jest wszystkim przeznaczonym do wykonania na komputerze . Na powierzchni brzmi nieźle, prawda? ale to naprawdę okazuje się dość brzydkie, gdy kopiesz głębiej.
   
  Rzecz w tym, że dobry kod uwzględnia problemy z czytelnością, a także poprawność wykonania - dzięki temu rozróżnienie „czytelność” jest bardzo bezużyteczne przy definiowaniu dokumentacji.
   
  Same próbki , o których wspomniałeś, pokazują, co jest z nimi nie tak. Klienci zazwyczaj oczekują, że będą one wyraźnie napisane iwykonać poprawnie. Naruszenie czytelności lub poprawności może przynieść wodospad skarg klientów. Naiwne rozróżnienie nie pomaga ustalić, czy próbki są kodem czy dokumentacją.
   
  Używanie naiwnego rozróżnienia stanie się jeszcze bardziej niechlujne, jeśli wyobrażasz sobie pracę z open source . Pobierasz, budujesz i uruchamiasz - nie czytasz, to tylko kod, prawda? Poczekaj, coś poszło nie tak i dostajesz się do kodu, aby przeczytać, co się tam dzieje ... hej, czytasz, nie wykonuj - czy ta dokumentacja jest teraz? I na koniec znajdziesz błąd w źródle i naprawisz go - teraz jest to naprawdę kod, nie jest to zwykle coś, co nazywa się dokumentacją, bez względu na to, jak dokładnie go przeczytasz, aby to naprawić.}

W przypadku „próbek” , które zamierzasz podać, rozróżnienie „nie modyfikuj” może okazać się bardzo ważne.

Spójrz, jeśli jakaś próbka nie powiedzie się, gdy zostanie uruchomiona bez zmian, w udokumentowanym środowisku referencyjnym, to twój błąd - błąd w dokumentacji, który musisz zaakceptować i naprawić, dobrze.

Teraz, jeśli jest problem ze zmodyfikowaną próbką lub środowiskiem, to już nie twoja wina - mam na myśli brak błędu w dokumentacji, ponieważ dokumenty nie są przeznaczone do modyfikacji. Jakakolwiek pomoc zapewniona użytkownikom w takim przypadku, byłaby objęta kategorią wsparcia, a nie poprawką.

Wszystko, co odpowiada na pytanie „jak to zrobić ...”, to dokumentacja.

Dla programistów oznacza to specyfikację wymagań („skąd mam wiedzieć, co napisać”), dokumenty projektowe („jak spełnić moje wymagania”), macierze identyfikowalności („skąd mam wiedzieć, że mój projekt spełnia wszystkie moje wymagania”), plany badań ( „jak znam swoje prace Kodeksem”), testy jednostkowe ( „skąd mam wiedzieć, mam safisfied wymóg X”), komentarze inline ( "jak mogę upewnić się, że obok ubogich schlub rozumie, dlaczego napisałem, że ten sposób ”), instrukcje wdrażania („ jak spakować ten produkt do instalacji ”) itp.

Dla użytkowników oznacza to instrukcje obsługi („jak korzystać z oprogramowania”), samouczki („jak korzystać z tej konkretnej funkcji”), informacje o wydaniu („skąd mam wiedzieć, jakie błędy zostały naprawione / zostały wprowadzone nowe funkcje błędów? dodano ”) itp.