Kwalifikacja: INF.03 - Tworzenie i administrowanie stronami i aplikacjami internetowymi oraz bazami danych

Wiele osób intuicyjnie myśli, że dobra instrukcja użytkownika powinna zawierać „wszystko o programie”, łącznie z tym, jak jest on zbudowany od środka. To dość częsty błąd. Instrukcja użytkownika to dokument stricte praktyczny, nastawiony na obsługę, a nie na analizę wewnętrznej logiki systemu. Dlatego wymagania sprzętowe są tam jak najbardziej na miejscu – użytkownik musi wiedzieć, czy aplikacja w ogóle uruchomi się na jego komputerze, jakiego systemu operacyjnego potrzebuje, ile pamięci RAM czy wolnego miejsca na dysku. To podstawowy element każdej sensownej instrukcji, spotykany w oprogramowaniu komercyjnym i open source. Podobnie opis instalacji programu jest absolutnie kluczowy. Bez przejrzystej procedury instalacji, najlepiej krok po kroku, z krótkimi komentarzami, wielu użytkowników po prostu nie poradzi sobie z poprawnym uruchomieniem aplikacji. W dobrych praktykach dokumentacyjnych (np. styl Microsoft, Atlassian, Red Hat) sekcje typu „Instalacja”, „Pierwsze uruchomienie”, „Konfiguracja wstępna” to standard. Trzecia kwestia to sposób działania poszczególnych komponentów, ale z perspektywy użytkownika, nie programisty. Nie chodzi o opisy klas, modułów czy bibliotek, tylko o to, co użytkownik widzi: okna, zakładki, panele, przyciski, formularze. Instrukcja powinna tłumaczyć, do czego służą konkretne elementy interfejsu, jakie mają opcje, co się stanie po wybraniu danej funkcji. Bez takiego opisu użytkownik błądzi po omacku. Problem zaczyna się wtedy, gdy do instrukcji użytkownika próbuje się wcisnąć opis zastosowanych algorytmów. To już jest poziom dokumentacji technicznej, przeznaczony dla deweloperów. Użytkownik końcowy nie potrzebuje wiedzieć, czy dane są sortowane quicksortem, mergesor­tem, jak działa algorytm szyfrowania albo jaka jest złożoność czasowa przetwarzania. Takie informacje nie pomagają mu wykonać zadania w aplikacji, tylko wprowadzają niepotrzebny chaos. Typowy błąd myślowy polega tu na mieszaniu dwóch różnych grup odbiorców: użytkowników i programistów. Dobrą praktyką jest ich rozdzielenie i trzymanie instrukcji użytkownika na poziomie funkcji, kroków i efektów, a nie implementacji.