Dobra dokumentacja oprogramowania, czy to dokumentacja specyfikacji dla programistów i testerów, dokumentacja techniczna dla użytkowników wewnętrznych, czy podręczniki i pliki pomocy dla użytkowników końcowych, pomoże użytkownikom zrozumieć cechy i funkcje oprogramowania. Dobra dokumentacja to dokumentacja, która jest konkretna, przejrzysta i istotna, zawierająca wszystkie informacje, których potrzebuje użytkownik. Ten artykuł poprowadzi Cię do pisania dokumentacji oprogramowania dla użytkowników technicznych i użytkowników końcowych.
Krok
Metoda 1 z 2: Pisanie dokumentacji oprogramowania dla użytkowników technicznych
Krok 1. Dowiedz się, jakie informacje uwzględnić
Dokument specyfikacji jest używany jako podręcznik referencyjny dla projektantów interfejsów, programistów piszących kod i testerów, którzy weryfikują wydajność oprogramowania. Informacje, które należy uwzględnić, będą zależeć od tworzonego programu, ale mogą obejmować:
- Ważne pliki w aplikacji, takie jak pliki utworzone przez zespół programistów, bazy danych, do których uzyskuje się dostęp podczas działania programu oraz aplikacje innych firm.
- Funkcje i podprogramy, w tym wyjaśnienie użycia funkcji/podprogramu, wartości wejściowe i wyjściowe.
- Zmienne i stałe programu oraz sposób ich użycia.
- Ogólna struktura programu. W przypadku programów opartych na dyskach może być konieczne opisanie każdego modułu i biblioteki. Lub, jeśli piszesz podręcznik do programu internetowego, być może będziesz musiał wyjaśnić, jakich plików używa każda strona.
Krok 2. Zdecyduj, jaki poziom dokumentacji powinien być obecny i możliwy do oddzielenia od kodu programu
Im więcej dokumentacji technicznej zawartej w kodzie programu, tym łatwiej będzie ją aktualizować i konserwować, a także wyjaśniać różne wersje programu. Dokumentacja w kodzie programu powinna zawierać przynajmniej funkcje, podprogramy, zmienne i stałe.
- Jeśli twój kod źródłowy jest długi, możesz napisać dokumentację w pliku pomocy, który następnie można indeksować lub przeszukiwać za pomocą określonych słów kluczowych. Oddzielne pliki dokumentacji są przydatne, jeśli logika programu jest podzielona na kilka stron i zawiera pliki pomocnicze, takie jak aplikacja internetowa.
- Niektóre języki programowania (takie jak Java, Visual Basic. NET czy C#) mają własne standardy dokumentacji kodu. W takich przypadkach postępuj zgodnie ze standardową dokumentacją, która musi być zawarta w kodzie źródłowym.
Krok 3. Wybierz odpowiednie narzędzie dokumentacji
W niektórych przypadkach narzędzie dokumentacji zależy od używanego języka programowania. Języki C++, C#, Visual Basic, Java, PHP i inne mają własne narzędzia dokumentacyjne. Jeśli jednak nie, użyte narzędzia będą zależeć od wymaganej dokumentacji.
- Procesor tekstu, taki jak Microsoft Word, nadaje się do tworzenia plików tekstowych dokumentów, o ile dokumentacja jest zwięzła i prosta. Do tworzenia długiej dokumentacji ze złożonym tekstem większość autorów tekstów technicznych wybiera specjalistyczne narzędzie do tworzenia dokumentacji, takie jak Adobe FrameMaker.
- Pliki pomocy do dokumentowania kodu źródłowego można tworzyć za pomocą programu do generowania plików pomocniczych, takiego jak RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare lub HelpLogix.
Metoda 2 z 2: Pisanie dokumentacji oprogramowania dla użytkowników końcowych
Krok 1. Poznaj powody biznesowe leżące u podstaw tworzenia podręcznika
Chociaż głównym powodem tworzenia dokumentacji oprogramowania jest pomoc użytkownikom w zrozumieniu, jak korzystać z aplikacji, istnieje kilka innych powodów, które mogą leżeć u podstaw tworzenia dokumentacji, takich jak pomoc działowi marketingu w sprzedaży aplikacji, poprawa wizerunku firmy i ograniczenie wsparcia technicznego koszty. W niektórych przypadkach dokumentacja jest wymagana, aby była zgodna z przepisami lub innymi wymogami prawnymi.
Jednak dokumentacja nie jest dobrym substytutem interfejsu. Jeśli aplikacja wymaga do działania dużej ilości dokumentacji, powinna być zaprojektowana tak, aby była bardziej intuicyjna
Krok 2. Poznaj grupę docelową dokumentacji
Ogólnie rzecz biorąc, użytkownicy oprogramowania mają ograniczoną wiedzę komputerową wykraczającą poza używane przez nich aplikacje. Istnieje kilka sposobów na zaspokojenie ich potrzeb w zakresie dokumentacji:
- Zwróć uwagę na tytuł użytkownika oprogramowania. Na przykład administrator systemu na ogół rozumie różne aplikacje komputerowe, podczas gdy sekretarka zna tylko te aplikacje, których używa do wprowadzania danych.
- Zwróć uwagę na użytkowników oprogramowania. Chociaż ich stanowiska są generalnie zgodne z wykonywanymi zadaniami, stanowiska te mogą mieć różne obciążenia, w zależności od miejsca prowadzenia działalności. Przeprowadzając wywiady z potencjalnymi użytkownikami, możesz dowiedzieć się, czy Twoja ocena ich stanowiska pracy jest prawidłowa.
- Zwróć uwagę na istniejącą dokumentację. Dokumentacja funkcji oprogramowania i specyfikacje mogą pokazywać, co użytkownicy muszą wiedzieć, aby z nich korzystać. Należy jednak pamiętać, że użytkownicy mogą nie być zainteresowani poznaniem „wnętrzności” programu.
- Dowiedz się, co jest potrzebne do wykonania zadania i zanim je ukończysz.
Krok 3. Określ odpowiedni format dokumentacji
Dokumentacja oprogramowania może być uporządkowana w 1 lub 2 formatach, a mianowicie podręczniki i podręczniki. Czasami połączenie tych dwóch formatów jest dobrym rozwiązaniem.
- Formaty referencyjne służą do opisu wszystkich funkcji oprogramowania, takich jak przyciski, karty, pola i okna dialogowe, oraz sposobu ich działania. Niektóre pliki pomocy są zapisywane w tym formacie, zwłaszcza te, które są zależne od kontekstu. Gdy użytkownik kliknie Pomoc na określonym ekranie, otrzyma odpowiedni temat.
- Format ręczny służy do wyjaśnienia, jak coś zrobić z oprogramowaniem. Podręczniki są zazwyczaj drukowane lub w formacie PDF, chociaż niektóre strony pomocy zawierają również instrukcje dotyczące wykonywania określonych czynności. (Ogólnie rzecz biorąc, formaty ręczne nie są zależne od kontekstu, ale mogą być powiązane z tematami kontekstowymi). Podręczniki mają zazwyczaj formę przewodnika, z podsumowaniem zadań do wykonania w opisie i przewodnikiem sformatowanym w krokach.
Krok 4. Zdecyduj o rodzaju dokumentacji
Dokumentacja oprogramowania dla użytkowników może być spakowana w jednym lub kilku z następujących formatów: drukowane podręczniki, pliki PDF, pliki pomocy lub pomoc online. Każdy rodzaj dokumentacji ma na celu pokazanie, jak korzystać z funkcji oprogramowania, niezależnie od tego, czy jest to przewodnik, czy samouczek. Dokumentacja online i strony pomocy mogą również zawierać filmy demonstracyjne, tekst i statyczne obrazy.
Pliki pomocy i wsparcia online powinny być indeksowane i przeszukiwane za pomocą słów kluczowych, aby użytkownicy mogli szybko znaleźć potrzebne informacje. Chociaż aplikacja generatora plików pomocy może automatycznie utworzyć indeks, nadal zaleca się tworzenie indeksu ręcznie przy użyciu często wyszukiwanych słów kluczowych
Krok 5. Wybierz odpowiednie narzędzie dokumentacji
Drukowane podręczniki lub pliki PDF można tworzyć za pomocą edytora tekstu, takiego jak Word, lub zaawansowanego edytora tekstu, takiego jak FrameMaker, w zależności od długości i złożoności pliku. Pliki pomocy można pisać za pomocą programu do tworzenia plików pomocy, takiego jak RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix lub HelpServer.
Porady
- Tekst dokumentacji programu powinien być skonstruowany w taki sposób, aby był łatwy do odczytania. Umieść obraz jak najbliżej odpowiedniego tekstu. Logicznie podziel dokumentację na sekcje i tematy. Każda sekcja lub temat powinien opisywać konkretny problem, zarówno zadanie, jak i funkcje programu. Powiązane kwestie można wyjaśnić za pomocą linków lub list referencyjnych.
- Każde z narzędzi dokumentacji opisanych w tym artykule można uzupełnić programem do tworzenia zrzutów ekranu, takim jak SnagIt, jeśli dokumentacja wymaga wielu zrzutów ekranu. Podobnie jak w przypadku każdej innej dokumentacji, powinieneś również dołączyć zrzuty ekranu, aby pomóc wyjaśnić, jak działa aplikacja, zamiast „zwabić” użytkownika.
- Zwracanie uwagi na styl jest bardzo ważne, zwłaszcza jeśli piszesz dokumentację oprogramowania dla użytkowników końcowych. Zwracaj się do użytkowników zaimkiem „ty”, zamiast „użytkownik”.
