Dokumentuje tworzoną aplikację

Dlaczego tak

Komentarz blokowy /* … */ obejmuje oba wiersze między znacznikami, więc mnożenie przez 10 i dodawanie 1 nie są wykonywane. W czwartym wierszu wykonuje się x = x * 3, a tekst po // to komentarz jednowierszowy, więc przypisanie 0 jest pominięte. Wynik to 2 · 3 = 6; wartość 63 powstałaby, gdyby komentarz blokowy obejmował tylko pierwszy wiersz.

Dlaczego tak

Komentarz dokumentacyjny w C# zaczyna się od trzech ukośników i zawiera znaczniki XML, takie jak summary, param czy returns – kompilator może zebrać je do pliku XML, z którego korzystają IntelliSense i generatory, np. DocFX. Komentarz z dwoma ukośnikami jest zwykłym komentarzem, nawet jeśli zawiera znaczniki. Znacznik @summary w bloku /* */ przypomina JSDoc, ale C# go nie interpretuje, a #region tylko zwija fragment kodu w edytorze.

Dlaczego tak

Pomoc kontekstowa wyświetla informacje dotyczące elementu, z którym użytkownik właśnie pracuje – zwykle po naciśnięciu F1 – zamiast otwierać spis treści całego podręcznika. ToolTip też dotyczy konkretnej kontrolki, ale jest krótkim dymkiem pojawiającym się po najechaniu myszą, a nie dokumentem pomocy. Samouczek prowadzi krok po kroku przez całe zadanie, a dokumentacja API jest przeznaczona dla programistów.

Dlaczego tak

Instrukcja użytkownika opisuje, jak wykonać zadanie w interfejsie – językiem użytkownika, krok po kroku, z nazwami przycisków i pól widocznymi na ekranie. Opis klas i wzorców projektowych, struktura bazy danych oraz zachowanie interfejsu API należą do dokumentacji technicznej, przeznaczonej dla programistów i administratorów. Użytkownik końcowy nie potrzebuje wiedzieć, jak aplikacja jest zbudowana, aby z niej korzystać.

Dlaczego tak

Instrukcja powinna prowadzić użytkownika w kolejności, w jakiej wykonuje czynności: najpierw sprawdza, czy jego komputer spełnia wymagania, potem instaluje program, uruchamia go i konfiguruje, a następnie poznaje funkcje. Rozdział o rozwiązywaniu problemów i najczęstszych błędach umieszcza się na końcu, bo korzysta się z niego w razie potrzeby. Wymagania podane po instalacji są bezużyteczne, bo użytkownik dowie się o nich za późno.

Dlaczego tak

Dokumentacja wdrożenia opisuje, jak przygotować środowisko i uruchomić aplikację: wymagania programowe, konfigurację (zmienne środowiskowe, połączenie z bazą), kroki instalacji, migracje bazy i sposób wycofania wersji. Makiety i paleta kolorów należą do projektu interfejsu, a notatki ze spotkań – do dokumentacji projektowej. Lista testów jest częścią dokumentacji testów i nie pomaga w instalacji.