Jak pisać dokumentację oprogramowania: 8 kroków

Dobra dokumentacja oprogramowania - niezależnie od tego, czy jest to dokument zawierający specyfikację wymagań dla programistów lub testerów, dokumentu technicznego dla użytkowników wewnętrznych, podręcznik do korzystania z oprogramowania lub podpowiedzi programu dla użytkowników - pomaga osobę pracującą z oprogramowaniem, zrozumieć jego charakterystyczne cechy i Funkcje. Postępuj zgodnie z poradami - Jak pisać dokumentację oprogramowania dla użytkowników technicznych i końcowych.

Kroki

Metoda 1 z 2:

Pisanie dokumentacji oprogramowania dla użytkowników technicznych.

jeden. Określ, które należy wymienić informacje. Dokumenty na temat wymagań oprogramowania służą jako podręcznik odniesienia dla projektantów interfejsu użytkownika, programistów, którzy piszą kod i testery, które sprawdzają, czy oprogramowanie działa w następujący sposób. Dokładne informacje zależą jednak od samego programu, może obejmować następujące informacje:

Kluczowe pliki w aplikacji. Mogą to być pliki utworzone przez zespół deweloperski, bazy danych spowodowane podczas operacji oprogramowania oraz programy serwisowe osób trzecich.
Funkcje i podprogramy. Wskazano tutaj, że każda funkcja i podprogram tworzy, w tym wartości wejściowe i wyjściowe.
Zmienne oprogramowania i stały i jak są używane w aplikacji.
Ogólna struktura programu. W przypadku aplikacji opartych na dysku prawdopodobnie będziesz potrzebował opisu poszczególnych bloków i bibliotek programowych, podczas gdy aplikacje internetowe będą potrzebować opisu stron, które używają plików.

Obraz zatytułowany Dokumentacja oprogramowania WPIS Krok 2

2. Zdecyduj, ile dokumentacji powinna być w Kodeksie Programu i ile należy oddzielić. Im więcej dokumentacji technicznej jest tworzona w kodzie programowym, tym łatwiej będzie aktualizować ten kod jako dokumentację odnoszącej się do różnych wersji oryginalnej aplikacji. Minimum, dokumentacja w Kodeksie Programu powinna wyjaśnić funkcje, podprogramy, stałe oprogramowania i zmienne.

Jeśli kod programu jest dość długo, można go umieścić jako plik odniesienia, w którym można wyszukiwać według słów kluczowych lub drogowskazów. Będzie to duży plus dla aplikacji, w których logika programu jest podzielona na wiele stron i zawiera numery plików pomocniczych, jak w niektórych aplikacjach internetowych.

Niektóre języki programowania, takie jak Java lub Net Framework (Visual Basic.Net, C #), mają swoje własne standardy do kodu dokumentacji. W takich przypadkach postępuj zgodnie ze standardowymi instrukcjami - ile dokumentacji powinna być zawarta w kodzie programu.

Obraz zatytułowany Dokumentacja oprogramowania WPIS Krok 3

3. Wybierz odpowiednie narzędzie. Do pewnego stopnia jest to definiowane przez język, na którym kod jest napisany, bądź nim C ++, C #, Visual Basic, Java lub PHP - dla każdego są nasze własne narzędzie. W innych przypadkach stosowane narzędzie jest określone przez wymagane typ dokumentacji.

Edytor tekstu "Microsoft Word"-Cercing narzędzie do tworzenia oddzielnych dokumentacji plików tekstowych, które będą proste i krótkie. W przypadku długich plików tekstowych wielu programistów dokumentacji technicznych woli wybrać program Adobe Framemaker.

Pliki wskazówek do dokumentacji kodu oprogramowania mogą być zapisywane przy użyciu dowolnego narzędzia, takiego jak robohelp, pomoc i ręczny, doc-to-help, flary Madcap, lub "Helplogix".

Metoda 2 z 2:

Pisanie dokumentacji oprogramowania dla użytkowników końcowych

jeden. Zidentyfikuj rozważania komercyjne dla dokumentacji. Chociaż przyczyny funkcjonalne dokumentacji oprogramowania mają pomóc użytkownikom zrozumieć, jak korzystać z aplikacji, istnieją inne powody, takie jak pomoc w promowaniu towarów na rynku, poprawiając wizerunek Spółki i najważniejszą rzeczą, zmniejszając koszty wsparcia technicznego. W niektórych przypadkach dokumentacja jest zobowiązana do wykonania pewnych zasad i wymogów prawnych.

W żadnym przypadku dokumentacja programu nie powinna zastąpić zły projekt interfejsu. Jeśli ekran aplikacji wymaga wiele dokumentacji wyjaśniającej, lepiej zmienić projekt do czegoś bardziej intuicyjnego.

Obraz zatytułowany Pisz dokumentacja oprogramowania Krok 5

2. Zrozumieć publiczność, dla której piszesz dokumentację. W większości przypadków użytkownicy oprogramowania niewiele wiedzą o komputerach oprócz zadań aplikacji. Istnieje kilka sposobów ustalenia, jak koordynować swoje potrzeby z dokumentacją.

Spójrz na zawody należące do potencjalnych użytkowników. Administrator systemu prawdopodobnie będzie ekspertem w użyciu aplikacji oprogramowania, podczas gdy operator wprowadzania danych prawdopodobnie posiadał aplikację, którą go lub obecnie używa do wprowadzania danych.

Spójrz na samych użytkowników. Chociaż ich posty ogólnie określają, w których ludzie są zaangażowani, ale istnieją znaczne różnice w zakresie określonych pozycji w tej organizacji. Prowadzenie wywiadu z potencjalnymi użytkownikami, możesz dodać swoją opinię - czy nazwa postu spełniła obowiązki.

Zobacz istniejącą dokumentację. Dokumentacja poprzednich wersji oprogramowania daje przybliżoną koncepcję, którą użytkownik musi wiedzieć o korzystaniu z programu. Pamiętaj jednak, że użytkownicy końcowi nie są zainteresowani tym, jak działa program, ważne jest, aby wiedzieć, co mogą z tym zrobić.

Określ zadania niezbędne do tej pracy i jakie zadania muszą być wykonywane przed wykonaniem tych zadań.

Obraz zatytułowany Dokumentacja oprogramowania Krok 6

3. Określ odpowiednie format dokumentacji. Dokumentacja oprogramowania może być ustrukturyzowana w jednym z dwóch formatów - przewodnika odniesienia i instrukcji użytkowania. Czasami lepiej wybrać mieszaną wersję tych dwóch formatów.

Podręcznik odniesienia jest przeznaczony do wyjaśnienia narzędzi oprogramowania (przyciski, tabele, pole i panel dialogowy) oraz jak działa ta zestaw narzędzi. W tym formacie są zapisywane w tym formacie, a monit kontekstowy pomagają pokazać żądany temat po kliknięciu użytkownika na przycisk "Pomoc" na żądanym ekranie.

Instrukcje użytkowania wyjaśnia, jak korzystać z oprogramowania do wykonania określonego zadania. Instrukcja użycia często ma drukowany przewodnik lub format PDF, chociaż niektóre monity obejmują tematy, jak wykonać określone zadanie. (Te tematy odniesienia zazwyczaj nie są kontekstowe, chociaż mogą być hiperłącze) Instrukcja użytkowania często ma formę książki referencyjnej z opisem zadania i instrukcje krok po kroku.

Obraz zatytułowany Dokumentacja oprogramowania WPIS Krok 7

cztery. Zdecyduj, jaki format (formaty) dokumentacji powinno być. Dokumentacja oprogramowania dla użytkowników końcowych może być jednym lub więcej formatami: Podręcznik drukowania, dokumenty w formacie PDF, pliki końcówki lub pomoc online. Każdy z tych formatów jest tworzony, aby wyświetlić użytkownikowi, jak korzystać z każdego funkcji programu - czy to krótki przegląd lub przewodnik. Podobnie jak w przypadku monitowych plików i pomocy online, dokumentacja może mieć wideo demonstracyjne lub tekst ze zdjęciami.

Porady i pliki pomocy online muszą mieć wskaźniki, wyszukiwanie według słów kluczowych, które pozwolą użytkownikowi szybko znaleźć wymagane informacje. Chociaż narzędzia do monitowych plików mogą automatycznie tworzyć wskaźniki, lepiej jest to zrobić ręcznie za pomocą terminów, które użytkownicy będą najprawdopodobniej wyszukiwanie.

Obraz zatytułowany Dokumentacja oprogramowania Krok 8

pięć. Wybierz odpowiednie narzędzie do tworzenia dokumentacji. Podręczniki drukowania lub format PDF można zapisać w edytorach tekstowych, takich jak "Word" lub "Framemaker", w zależności od długości i złożoności podręcznika. Pliki wskazówkowe mogą być zapisywane przy użyciu takich narzędzi programistycznych, takich jak "Robohelp", "Pomoc i podręcznik", "doc-to-help", "Flare", "Helplogix" lub "Helpserver".

Rada

Tekst powinien być łatwy do odczytania, zdjęcia powinny znajdować się jak najbliżej tekstu, do którego należą. Przesuń dokumentację na sekcje i motywy logiczne. Każda sekcja lub temat powinna dotyczyć pewnego pytania, niezależnie od tego, czy jest to jeden program lub zadanie. Poniższe pytania powinny być wskazane "do oglądania również" z hiperłączem, jeśli jest to wymagane.
Wszystkie narzędzia do tworzenia dokumentacji wymienione powyżej można uzupełnić programem zrzutu ekranu, takiego jak snagit, jeśli dokumentacja wymaga pewnej liczby zrzutów ekranu. Podobnie jak w przypadku drugiej dokumentacji, zrzuty ekranu powinni wyjaśnić, w jaki sposób działa oprogramowanie, a nie wprowadzać w błąd użytkownika.
Ważne jest również ton dokumentacji pisania, zwłaszcza jeśli jest napisany dla użytkowników końcowych. Użyj drugiej twarzy "Ty", zamiast stron trzecich "Użytkownicy".

Czego potrzebujesz

Narzędzie do pisania dokumentacji / DeBulu
Narzędzie do tworzenia ekranu