Jak pisać dokumentację oprogramowania
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.

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.

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.
Metoda 2 z 2:
Pisanie dokumentacji oprogramowania dla użytkowników końcowychjeden. 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.

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

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.

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.

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