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)
źródło
Odpowiedzi:
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.
źródło
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ę:
źródło
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.
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ą.
źródło
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.źródło