Co dokładnie obejmuje „dokumentację”?

12

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)

Dan McGrath
źródło
2
Komentarze do notek zawsze mile widziane. Niestety liczby nie zawierają zbyt konstruktywnej krytyki, aby zrozumieć, gdzie się zbłądził :)
Dan McGrath
1
Dokumentacja oprogramowania lub dokumentacja kodu źródłowego jest tekstem towarzyszącym oprogramowaniu komputerowemu. Wyjaśnia, jak to działa lub jak z niego korzystać, i może oznaczać różne rzeczy dla osób pełniących różne role. - Kluczowe zdanie brzmi „może oznaczać różne rzeczy dla ludzi w różnych rolach”, jaka jest twoja publiczność? (Jeszcze nie głosowałem, ale sądzę, że to wina niejasności i otwartości tego pytania).
yannis
2
To pytanie krzyczy, żeby ktoś narysował diagram Venna.
MathAttack

Odpowiedzi:

6

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
Materiały szkoleniowe uważam za dokumentację tylko wtedy, gdy są one wytwarzane / dystrybuowane przez ten sam zespół (w szerokim znaczeniu), który wyprodukował oprogramowanie. Kursy innych firm nie są dokumentami.
Donal Fellows
Oczywiście że są. Dokumentacja strony trzeciej jest dokumentacją, nawet jeśli nie jest pod twoją kontrolą (i nie jest twoją odpowiedzialnością za tworzenie): służy czytelnikowi w wyjaśnieniu im tego. Jeśli masz problem z tym, że ludzie piszą dokumentację, która nie jest pod twoją kontrolą, powinieneś zrezygnować z takiej dokumentacji.
2

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ć.
DXM
źródło
Powiedzenie, że podjąłem niewłaściwą część rozmowy opartej na jednym pytaniu, jest nieco dużym wnioskiem do wyciągnięcia z jednego pytania :) Jestem nowy w tej firmie i pomagam w ulepszaniu. Podanie liczby „klientów” ponad 10 000 programistów (piszemy bazy danych) negocjowanie z nimi wszystkimi jest nieco trudne (chociaż staram się - prowadzić grupy fokusowe, rady doradcze itp.). Nie zgadzam się z twoją odpowiedzią, ale po prostu szukałem tego, co może być / nie rozważam dokumentacji dla tej części rozmowy, więc mogę mieć punkt danych na początek, który nie jest tylko moją opinią.
Dan McGrath
@DanMcGrath: przepraszam, często pocieram PMs, w tym mój własny, w niewłaściwy sposób :) Niezależnie od przyjętego wniosku, który wyciągnąłem z twojego Q, nadal utrzymywałbym, że „wszystko”, co pasuje do kodu, można rozważyć "dokumentacja". Gdybym był tobą, zamiast pytać „czym może być dokumentacja” i kompilować wyczerpującą listę różnych rzeczy (kiedyś miałem serwetkę referencyjną ze schematem UML), wróciłbym do bazy klientów i zapytałbym im to, czego potrzebują. Jeśli nikt nie powie „Chcę samouczek wideo”, dlaczego miałbym spędzać jakiekolwiek cykle mózgowe, nawet biorąc to pod uwagę?
DXM
Nie ma problemu DXM. Też jestem tylko nowym PMem, dopiero niedawno golę swoje kody (częściowo). Byłem bardziej zainteresowany, aby zobaczyć, czy ktoś wrócił z czymś, czego nie wziąłem pod uwagę ani jako koncepcję, ani jako artefakt do rozważenia. Jestem wielkim fanem pytania „jaki jest twój problem” i zachęcania naszego zespołu do współpracy z klientami, a nie pytania „co chcesz, abyśmy zrobili”. Wzdłuż tych samych linii co [„Chcemy poruszać się szybciej” -> Budujemy samochody] vs [„Chcemy, abyś dał nam szybsze konie”]. Posiadanie nam wielu informacji pod ręką pomaga wspólnie znaleźć bardziej prawdopodobne rozwiązanie.
Dan McGrath
2

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ą.

komar
źródło
2

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.

John Bode
źródło