Dokumentacja oprogramowania - Software documentation

Dokumentacja oprogramowania to napisany tekst lub ilustracja, która towarzyszy oprogramowaniu komputerowemu lub jest osadzona w kodzie źródłowym. Dokumentacja wyjaśnia, jak działa oprogramowanie lub jak z niego korzystać, i może mieć różne znaczenie dla osób pełniących różne role.

Dokumentacja jest ważną częścią inżynierii oprogramowania . Rodzaje dokumentacji obejmują:

  • Wymagania — oświadczenia identyfikujące atrybuty, możliwości, cechy lub cechy systemu. To jest podstawa tego, co będzie lub zostało wdrożone.
  • Architektura/Projektowanie – Przegląd oprogramowania. Obejmuje relacje ze środowiskiem i zasady konstrukcyjne, które mają być stosowane w projektowaniu komponentów oprogramowania.
  • Techniczne – Dokumentacja kodu, algorytmów, interfejsów i API .
  • Użytkownik końcowy — instrukcje dla użytkownika końcowego, administratorów systemu i personelu pomocniczego.
  • Marketing – Jak wprowadzić produkt na rynek i analiza popytu rynkowego.

Dokumentacja wymagań

Dokumentacja wymagań to opis tego, co robi lub ma robić dane oprogramowanie . Jest używany podczas tworzenia oprogramowania, aby komunikować, w jaki sposób oprogramowanie działa lub jak ma działać. Jest również używany jako umowa lub jako podstawa do uzgodnienia tego, co będzie robić oprogramowanie. Wymagania są tworzone i konsumowane przez wszystkich zaangażowanych w produkcję oprogramowania, w tym: użytkowników końcowych , klientów , kierowników projektów , sprzedaż , marketing , architektów oprogramowania , inżynierów użyteczności , projektantów interakcji , programistów i testerów .

Wymagania występują w różnych stylach, notacjach i formalnościach. Wymagania mogą być zbliżone do celu (np. rozproszone środowisko pracy ), zbliżone do projektu (np. kompilacje można rozpocząć, klikając prawym przyciskiem myszy plik konfiguracyjny i wybierając funkcję „buduj” ), oraz wszystko pomiędzy. Można je określić jako twierdzenia w języku naturalnym , jako rysunki, szczegółowe wzory matematyczne oraz jako kombinację ich wszystkich.

Różnorodność i złożoność dokumentacji wymagań sprawia, że ​​jest to sprawdzone wyzwanie. Wymagania mogą być ukryte i trudne do wykrycia. Trudno dokładnie wiedzieć, ile i jakiego rodzaju dokumentacja jest potrzebna, a ile można pozostawić dokumentacji architektoniczno-projektowej i trudno wiedzieć, jak udokumentować wymagania, biorąc pod uwagę różnorodność osób, które będą czytać i korzystać z dokumentacji . Dlatego dokumentacja wymagań jest często niekompletna (lub nie istnieje). Bez odpowiedniej dokumentacji wymagań zmiany oprogramowania stają się trudniejsze — a przez to bardziej podatne na błędy (spadek jakości oprogramowania ) i czasochłonne (kosztowne).

Potrzeba dokumentacji wymagań jest zazwyczaj związana ze złożonością produktu, wpływem produktu i oczekiwaną długością życia oprogramowania. Jeśli oprogramowanie jest bardzo złożone lub opracowane przez wiele osób (np. oprogramowanie telefonu komórkowego), wymagania mogą pomóc w lepszym komunikowaniu tego, co należy osiągnąć. Jeśli oprogramowanie ma kluczowe znaczenie dla bezpieczeństwa i może mieć negatywny wpływ na ludzkie życie (np. systemy energetyki jądrowej, sprzęt medyczny, sprzęt mechaniczny), często wymagana jest bardziej formalna dokumentacja wymagań. Jeśli oczekuje się, że oprogramowanie będzie działać tylko przez miesiąc lub dwa (np. bardzo małe aplikacje na telefony komórkowe opracowane specjalnie dla określonej kampanii), może być potrzebna bardzo niewielka dokumentacja wymagań. Jeśli oprogramowanie jest pierwszym wydaniem, które zostanie później zbudowane, dokumentacja wymagań jest bardzo pomocna podczas zarządzania zmianą oprogramowania i sprawdzania, czy nic nie zostało uszkodzone w oprogramowaniu podczas jego modyfikacji.

Tradycyjnie wymagania są określane w dokumentach wymagań (np. przy użyciu edytorów tekstu i arkuszy kalkulacyjnych). Aby zarządzać rosnącą złożonością i zmieniającym się charakterem dokumentacji wymagań (i ogólnie dokumentacji oprogramowania), zalecane są systemy zorientowane na bazę danych i specjalne narzędzia do zarządzania wymaganiami .

Dokumentacja projektowa architektury

Dokumentacja architektury (znana również jako opis architektury oprogramowania ) jest szczególnym rodzajem dokumentu projektowego. Dokumenty architektury są w pewnym sensie trzecią pochodną kodu ( dokument projektowy jest drugą pochodną, ​​a dokumenty kodowe są pierwszym). Bardzo niewiele w dokumentach dotyczących architektury jest specyficzne dla samego kodu. Dokumenty te nie opisują, jak zaprogramować konkretną procedurę, ani nawet dlaczego ta konkretna procedura istnieje w takiej formie, w jakiej istnieje, ale jedynie określają ogólne wymagania, które motywowałyby istnienie takiej procedury. Dobry dokument o architekturze zawiera mało szczegółów, ale zawiera wiele wyjaśnień. Może to sugerować podejścia do projektowania niższego poziomu, ale pozostawić faktyczne badania handlu wydobywczego innym dokumentom.

Innym rodzajem dokumentu projektowego jest dokument porównawczy lub studium handlowe. Często przybierałoby to formę białej księgi . Koncentruje się na jednym konkretnym aspekcie systemu i sugeruje alternatywne podejścia. Może to być interfejs użytkownika , kod, projekt, a nawet poziom architektury. Opisuje sytuację, opisuje jedną lub więcej alternatyw i wymienia zalety i wady każdej z nich. Dobry dokument dotyczący studiów handlowych zawiera dużo badań, jasno wyraża swoją ideę (bez zbytniego opierania się na tępym żargonie, który mógłby olśnić czytelnika) i, co najważniejsze, jest bezstronny. Powinna uczciwie i jasno wyjaśnić koszty najlepszego rozwiązania, jakie oferuje. Celem badania handlu jest opracowanie najlepszego rozwiązania, a nie forsowanie konkretnego punktu widzenia. Całkowicie akceptowalne jest brak wniosków lub stwierdzenie, że żadna z alternatyw nie jest wystarczająco lepsza niż podstawowa, aby uzasadnić zmianę. Należy do niego podchodzić jako do przedsięwzięcia naukowego, a nie jako techniki marketingowej.

Bardzo ważną częścią dokumentu projektowego w tworzeniu oprogramowania dla przedsiębiorstw jest dokument projektu bazy danych (DDD). Zawiera koncepcyjne, logiczne i fizyczne elementy projektu. DDD zawiera formalne informacje, których potrzebują osoby, które wchodzą w interakcję z bazą danych. Celem jej przygotowania jest stworzenie wspólnego źródła, z którego będą mogli korzystać wszyscy gracze na scenie. Potencjalni użytkownicy to:

W przypadku relacyjnych systemów baz danych dokument powinien zawierać następujące części:

  • Podmiot - schemat relacji ( rozszerzony lub nie), w tym następujące informacje i ich jasne definicje:
    • Zestawy encji i ich atrybuty
    • Związki i ich atrybuty
    • Klucze kandydujące dla każdego zestawu encji
    • Ograniczenia oparte na atrybutach i krotkach
  • Schemat relacyjny, zawierający następujące informacje:
    • Tabele, atrybuty i ich właściwości
    • Wyświetlenia
    • Ograniczenia takie jak klucze podstawowe, klucze obce,
    • Liczność ograniczeń referencyjnych
    • Polityka kaskadowa dla ograniczeń referencyjnych
    • Klucze podstawowe

Bardzo ważne jest, aby zawrzeć wszystkie informacje, które mają być używane przez wszystkich aktorów na scenie. Bardzo ważne jest również aktualizowanie dokumentów, ponieważ wszelkie zmiany zachodzą również w bazie danych.

Dokumentacja techniczna

Ważne jest, aby dokumenty kodu powiązane z kodem źródłowym (które mogą zawierać pliki README i dokumentację API ) były dokładne, ale nie tak szczegółowe, że ich utrzymanie staje się zbyt czasochłonne lub trudne. Różne poradniki i przewodniki po dokumentacji opisowej są często spotykane w odniesieniu do aplikacji lub produktu oprogramowania, które są dokumentowane przez autorów API . Dokumentacja ta może być wykorzystywana przez programistów, testerów, a także użytkowników końcowych. Obecnie istnieje wiele zaawansowanych aplikacji w dziedzinie energetyki, energetyki, transportu, sieci, lotnictwa, bezpieczeństwa, automatyki przemysłowej i wielu innych. Dokumentacja techniczna stała się ważna w takich organizacjach, ponieważ podstawowy i zaawansowany poziom informacji może zmieniać się wraz ze zmianami architektury.

Dokumenty kodu są często zorganizowane w stylu przewodnika referencyjnego , co pozwala programiście na szybkie wyszukanie dowolnej funkcji lub klasy.

Dokumentacja techniczna osadzona w kodzie źródłowym

Często narzędzia takie jak Doxygen , Ndoc , Visual Expert , Javadoc , JSDoc , EiffelStudio , Sandcastle , ROBODoc , POD , TwinText lub Universal Report mogą być używane do automatycznego generowania dokumentów kodu — to znaczy wyodrębniają komentarze i umowy dotyczące oprogramowania , jeśli to możliwe, z kodu źródłowego i tworzyć podręczniki referencyjne w postaci plików tekstowych lub HTML .

Idea automatycznego generowania dokumentacji jest atrakcyjna dla programistów z różnych powodów. Na przykład, ponieważ jest on wyodrębniany z samego kodu źródłowego (na przykład poprzez komentarze ), programista może napisać go odwołując się do kodu i użyć tych samych narzędzi, których używa do tworzenia kodu źródłowego do tworzenia dokumentacji. Ułatwia to aktualizowanie dokumentacji.

Oczywiście wadą jest to, że tylko programiści mogą edytować tego rodzaju dokumentację i od nich zależy odświeżenie danych wyjściowych (na przykład poprzez uruchomienie zadania cron, aby aktualizować dokumenty co noc). Niektórzy opisaliby to jako zaletę, a nie wadę.

Programowanie piśmienne

Szanowany informatyk Donald Knuth zauważył, że dokumentacja może być bardzo trudnym procesem, który wymaga przemyśleń, i opowiadał się za piśmiennym programowaniem , pisanym w tym samym czasie i miejscu co kod źródłowy i pobieranym automatycznie. Języki programowania Haskell i CoffeeScript mają wbudowaną obsługę prostej formy piśmiennego programowania, ale ta obsługa nie jest powszechnie stosowana.

Programowanie wyjaśniające

Programowanie wyjaśniające jest wynikiem praktycznych zastosowań Literate Programming w rzeczywistych kontekstach programowania. Paradygmat wyjaśniający proponuje, aby kod źródłowy i dokumentacja były przechowywane oddzielnie.

Często twórcy oprogramowania muszą mieć możliwość tworzenia i uzyskiwania dostępu do informacji, które nie będą częścią samego pliku źródłowego. Takie adnotacje są zwykle częścią kilku działań związanych z tworzeniem oprogramowania, takich jak spacery po kodzie i przenoszenie, gdzie kod źródłowy stron trzecich jest analizowany w sposób funkcjonalny. Adnotacje mogą zatem pomóc programiście na każdym etapie tworzenia oprogramowania, na którym formalny system dokumentacji utrudniałby postęp.

Dokumentacja użytkownika

W przeciwieństwie do dokumentów kodowych, dokumenty użytkownika po prostu opisują sposób użycia programu.

W przypadku biblioteki oprogramowania dokumenty kodu i dokumenty użytkownika mogą w niektórych przypadkach być efektywnie równoważne i warte połączenia, ale w przypadku ogólnych zastosowań często nie jest to prawdą.

Zazwyczaj dokumentacja użytkownika opisuje każdą funkcję programu i pomaga użytkownikowi w realizacji tych funkcji. Bardzo ważne jest, aby dokumenty użytkownika nie były zagmatwane i były aktualne. Dokumenty użytkownika nie muszą być zorganizowane w żaden szczególny sposób, ale bardzo ważne jest, aby posiadały dokładny indeks . Bardzo cenna jest również spójność i prostota. Dokumentacja użytkownika jest uważana za umowę określającą, co będzie robić oprogramowanie. Pisarze API są bardzo dobrze przygotowani do pisania dobrych dokumentów użytkownika, ponieważ byliby dobrze świadomi architektury oprogramowania i stosowanych technik programowania. Zobacz także pismo techniczne .

Dokumentacja użytkownika może być tworzona w różnych formatach online i drukowanych. Istnieją jednak trzy ogólne sposoby organizacji dokumentacji użytkownika.

  1. Samouczek: Podejście samouczka jest uważane za najbardziej przydatne dla nowego użytkownika, w którym jest prowadzony przez każdy etap wykonywania określonych zadań.
  2. Tematyczne: Podejście tematyczne , w którym rozdziały lub sekcje koncentrują się na jednym konkretnym obszarze zainteresowania, ma bardziej ogólne zastosowanie dla użytkownika pośredniego. Niektórzy autorzy wolą przekazywać swoje pomysły za pomocą artykułów opartych na wiedzy, aby ułatwić zaspokojenie potrzeb użytkowników. Takie podejście jest zwykle praktykowane w dynamicznym przemyśle, takim jak technologia informacyjna .
  3. Lista lub odniesienie: Ostatnim rodzajem zasady organizowania jest taka, w której polecenia lub zadania są po prostu pogrupowane alfabetycznie lub logicznie, często za pomocą indeksów z odsyłaczami. To drugie podejście jest bardziej przydatne dla zaawansowanych użytkowników, którzy dokładnie wiedzą, jakiego rodzaju informacji szukają.

Powszechną skargą wśród użytkowników dotyczącą dokumentacji oprogramowania jest to, że tylko jedno z tych trzech podejść zostało niemal wykluczone z pozostałych dwóch. Powszechne jest ograniczanie dostarczonej dokumentacji oprogramowania dla komputerów osobistych do pomocy online, która zawiera jedynie informacje referencyjne dotyczące poleceń lub elementów menu. Zadanie udzielania korepetycji nowym użytkownikom lub pomagania bardziej doświadczonym użytkownikom w maksymalnym wykorzystaniu programu jest pozostawione prywatnym wydawcom, którym często udziela się znaczącej pomocy ze strony twórców oprogramowania.

Tworzenie dokumentacji użytkownika

Podobnie jak inne formy dokumentacji technicznej, dobra dokumentacja użytkownika korzysta ze zorganizowanego procesu rozwoju. W przypadku dokumentacji użytkownika proces, jak to zwykle bywa w przemyśle, składa się z pięciu kroków:

  1. Analiza użytkownika , podstawowa faza badawcza procesu.
  2. Planowanie, czyli właściwa faza dokumentacji.
  3. Przegląd projektu, etap nie wymagający wyjaśnień, w którym oczekiwana jest informacja zwrotna na temat projektu utworzonego w poprzednim kroku.
  4. Testowanie użyteczności , w ramach którego użyteczność dokumentu jest testowana empirycznie.
  5. Edycja , ostatni krok, w którym informacje zebrane w kroku trzecim i czwartym są wykorzystywane do przygotowania ostatecznej wersji roboczej.

Kontrowersje związane z dokumentacją i zwinnym rozwojem

„Opór wobec dokumentacji wśród programistów jest dobrze znany i nie wymaga podkreślenia”. Ta sytuacja jest szczególnie powszechna w zwinnym tworzeniu oprogramowania, ponieważ te metodologie starają się unikać wszelkich niepotrzebnych czynności, które nie przynoszą bezpośrednio wartości. W szczególności Manifest Agile zaleca przedkładanie „działającego oprogramowania nad obszerną dokumentację”, co można by zinterpretować cynicznie jako „Chcemy spędzać cały nasz czas na kodowaniu. Pamiętaj, że prawdziwi programiści nie piszą dokumentacji”.

Ankieta wśród ekspertów inżynierii oprogramowania wykazała jednak, że dokumentacja w żadnym wypadku nie jest uważana za niepotrzebną w zwinnym rozwoju. Jednak uznaje się, że w rozwoju występują problemy motywacyjne i że mogą być potrzebne metody dokumentacji dostosowane do zwinnego rozwoju (np. poprzez systemy reputacji i grywalizację ).

Dokumentacja marketingowa

W przypadku wielu zastosowań konieczne jest posiadanie materiałów promocyjnych, aby zachęcić przypadkowych obserwatorów do spędzenia większej ilości czasu na poznawaniu produktu. Ta forma dokumentacji ma trzy cele:

  1. Aby podekscytować potencjalnego użytkownika produktem i zaszczepić w nim chęć większego zaangażowania się w niego.
  2. Aby poinformować ich o tym, co dokładnie robi produkt, aby ich oczekiwania były zgodne z tym, co otrzymają.
  3. Wyjaśnienie pozycji tego produktu w odniesieniu do innych alternatyw.

Zobacz też

Uwagi