Niniejszy artykuł opisuje zasady tworzenia instrukcji znajdujących się na witrynie ready-os.com. Obecnie jest to DRAFT czyli kopia robocza, ale w ciągu dwóch tygodni (do 25 czerwca) chcemy aby te zasady zostały wspólnie ustalone.

Zasady tworzenia instrukcji użytkownika Ready_™

Spis treści:

1) Zakres instrukcji
2) Wymagania dla artykułów
3) Konwencja
4) Hierarchia tematów
5) Hyperlinki
6) Testowanie i wprowadzanie poprawek
7) Tłumaczenie

 

1) Zakres instrukcji

Instrukcja pomocy użytkownika Ready_™ obejmuje:

  • Instrukcje dla każdej aplikacji
  • Instrukcje dla każdego modułu systemowego
  • Guideline dla obszarów biznesowych: CRM, PM, BPM, DMS.
  • Guideline dla wybranych branż: firmy budowlane, kancelarie prawne

2) Wymagania dla artykułów

Każda instrukcja najlepiej jakby zaczynała się od … zrzutu ekranu głównego okna w formie schematu z odnośnikami/liniami prowadzącymi do przycisków i listą dostępnych operacji poniżej, które w formie linków prowadzą do opisów na stronie instrukcji. Każdy opis funkcji rozdzielony jest nagłówkiem drugiego poziomy (H2) i ma nadane id <h2 id=”id-naglowka”>, które pozwala utworzyć kotwicę w spisie <a href=”id-naglowka”>Link</a>. [?]

W dalszej części powinna dzielić się na podartykuły obejmujące Konfigurację i Przypadki użycia. A może inaczej…?

Aby podział był czytelny dobrze jest podzielić tematy wg ról. Np. dla wniosków urlopowych mogą to być role: Pracownik, Kierownik, Kadry. Dla obiegu faktur: Sekretariat, Księgowość, Opisujący, Akceptant, Zarząd, Dział zakupów.

Osobne tematy, które wymagają opisów szerszych niż 1 strona tekstu mogą być umieszczane w osobnych podartykułach.

Niezbędne jest używanie sprawdzania pisowni, oraz przegląd dokumentu po jego utworzeniu pod kątem poprawności gramatycznej i składniowej. Niedopracowane zdania zawierające tego typu błędy, nie tylko nie dają się zrozumieć podczas czytania, ale również świadczą o braku profesjonalizmu firmy tworzącej produkt (takie instrukcje można spotkać często w tanich chińskich urządzeniach). Skrócone zasady stawiania przecinków: opracować na podstawie np. tego.

Dodatkowe wskazówki dla poprawy User eXperience

  • Unikajmy wieloznaczności. Dobra instrukcja posługuje się terminami jednoznacznymi. Czyli wszędzie gdzie mamy do czynienia z nazwami wieloznacznymi (np. dokument może oznaczać dla użytkownika plik Word, ale również otwartą formatkę).
  • Opisujmy wstępne założenia (prerequesities) – bez których nie można rozpocząć opisanego procesu np. w instrukcji przygotowania oferty z produktami, musi być spełnione założenie: Dodane produkty w bazie produktów oraz dodany kontrahent w bazie klientów.
  • Układajmy instrukcję wg problemów z domeny użytkownika – czyli w języku zadań, które użytkownik chce wykonać, nawet nie znając jeszcze programu i jego terminologii. Np. chcąc nakierować użytkownika na podpowiedź w temacie wysyłania zaproszeń na spotkania w mailu, może on nie znaleźć tego w temacie „Dodawanie osób kontaktowych do zdarzeń”. Co prawda taka jest przyjęta przez nas logika tej operacji – że dodaje się osoby i można zaznaczyć pojawiającą się po zapisie opcję „Wyślij zaproszenie” – ale użytkownik zanim tego nie wypróbuje to nie wie i będzie szukał nagłówka/tematu w stylu „Wysyłanie zaproszeń do spotkań/outlook”.
  • Używajmy diagramów przepływu dla opisania bardziej złożonego procesu lub sekwencji czynności. Szczególnie jeśli dotyczy to procesów z podziałem na kilka ról.
  • Dla zobrazowania schematów powiązań i zależności konfiguracji utwórzmy model strukturalny danych. Pozwoli on 10 razy szybciej zorientować się w zależnościach niż tasiemcowy opis.

3) Konwencja

Formy osobowe

Instrukcja powinna jednolicie posługiwać się formami osobowymi wg zasad:
Po pierwsze dla całości treści zalecane jest użycie stylu bezosobowego np:
System pozwala na rejestrację wielu faktur…
Za pomocą przycisku X można uruchomić funkcję Y…

Nie przeszkadza wplatanie w niego pierwszej osoby liczby mnogiej np:

Po otwarciu formatki faktury widzimy podgląd pliku…
Za pomocą modułu X można wykonać wiele zadań, ale w tym celu musimy wcześniej skonfigurować obiekt Y.

Do przedstawienia sekwencji czynności wygodniejsza w czytaniu i z tego względu prawidłowa będzie również druga osoba liczby pojedynczej w trybie rozkazującym np:

System pozwala na wystawianie faktur sprzedaży. Aby wystawić fakturę postępujemy wg kolejnych czynności:
1) otwórz okno,
2) przejdź do zakładki…
3) następnie uruchom przycisk…

Nie należy się jednak zwracać w pozostałych przypadkach bezpośrednio do użytkownika np. System daje Ci możliwość uruchomienia procedury obiegu dokumentu.

 

Słownik pojęć

W tym miejscu znajduje się słownik pojęć używanych w systemie. Pozwoli on przyjąć jednolite i pożądane formy dla nazywania podobnych obiektów np. dokument vs metryka, plik vs. załącznik,  formularz vs kartoteka itp.

Sposób tworzenia i osadzania screenów

Screeny powinny pokazywać … Należy wykonywać je w rozdzielczości … Powinny być docięte tak by pokazywać szczegół…

Na stronie instrukcji powinny być zawsze wyrównane do lewej. Dopuszczalne jest oblewanie screena tekstem wyjaśniającym obrazek, ale z zachowaniem odpowiedniego padding (25px). Opcjonalnie screeny mogą być podpisane – wówczas należy zastosować styl Caption (pomniejszony font podstawowy + kursywa)

Sposób tworzenia schematów

Jeden obraz wart jest tysiąca słów. Dlatego warto przygotować do wyjaśnienia procesu i złożonych zależności odpowiednie rysunki i schematy. W tym celu powinniśmy ujednolicić stosowane narzędzia i efekty. Propozycja by wykorzystać do schematu procesu graficznego załączony w bazie wiedzy PowerPoint i zestaw przygotowanych symboli, a do schematów danych program…

4) Hierarchia tematów

… Użytkownik po wejściu w pomoc powinien otrzymać łatwą nawigację zawierającą przede wszystkim linki wraz z graficznymi symbolami aplikacji. Pozostałe zastosowania powinny być dostępne w formie linków pogrupowanych wg obszarów: Instrukcje dla użytkownika, Instrukcje dla administratora, Przewodniki branżowe, Przewodniki dla rozwiązań [?] …

5) Testowanie i wprowadzanie poprawek

Każda instrukcja podobnie jak kod programu powinna być przetestowana – tj. musi każdą instrukcję przeczytać odpowiednio uświadomiona osoba, która zweryfikuje nie tylko zawartość merytoryczną, ale również to, czy stosując kroki zawarte w instrukcji użytkownik rzeczywiście dochodzi do celu.

W tym celu stosujemy następującą procedurę:

….

6) Hyperlinki i SEO

Zastosowanie jednej strony www dla instrukcji ma tą zaletę, że strona może zostać całkiem nieźle wypozycjonowana w Google. Ponadto umieszczone w niej linki do powiązanych aplikacji pomogą w utworzeniu przez algorytmy Google semantycznej sieci powiązań całego obszaru pokrywanego przez system. Do weryfikacji tego czy strona jest dobrze zoptymalizowana pod SEO służy wtyczka YoastSEO. Wtyczka jest widoczna na dole edytowanego artykułu i w formie podpowiedzi i sugestii pozwala uzyskać lepiej czytelną i bardziej zoptymalizowaną treść. Oto kilka głównych wskazówek:

1) Link do strony z opisem aplikacji (tej dostępnej z menu Aplikacje).

W treści linku użyj wpisanego do sekcji SEO słowa kluczowego np. dla aplikacji do obiegu faktur jest to: „obieg faktur”. Słowa kluczowe zostaną wpisane przez Content Managera, jeśli ich nie ma to możemy skorzystać z mapy słów kluczowych udostępnionej w bazie wiedzy.

Jeśli jest to podartykuł, to należy umieścić link do artykułu głównego instrukcji tej aplikacji/modułu.

2) Poszczególne sekcje tekstu nie powinny być zbyt długie

Chodzi o to, by nad każdym dłuższym fragmentem tekstu był nagłówek (h2, h3, h4 itd., czyli nagłówek drugiego stopnia, trzeciego itd.). Każda z takich sekcji tekstu powinna być krótsza niż 300 słów.

3) Poszczególne akapity nie mogą być zbyt długie

Czytając książkę długie akapity nie mają aż takiego znaczenia, ale czytając na ekranie kwestia długości akapitu często decyduje o tym, czy użytkownik podejmie trud jego przeczytania. Dlatego, aby ułatwić czytanie warto stosować krótkie akapity. Pod każdym z takich akapitów tworzy się krótka przerwa. Zresztą spójrz na ten artykuł. Akapity mają zazwyczaj 3-4 linijki.

4) Poszczególne zdania nie mogą być zbyt długie

Co to znaczy długie zdanie? Takie, które zbudowane jest z więcej niż 20 wyrazów. Unikaj tak długich zdań, ponieważ taki tekst się czyta trudniej. Długie zdania czasem są konieczne, ale powinny stanowić maksymalnie 15% wszystkich zdań w tekście.

5) Frazy wzbogacające

Co to są te frazy wzbogacające?

  • wyliczenia: po pierwsze, przede wszystkim, także, wreszcie
  • przyczyny: ponieważ, więc, z tego powodu
  • porównania: podobnie, podczas gdy, w przeciwieństwie
  • wnioski: w rezultacie, w związku z tym
  • sygnały rozmyte: wydaje się, być może, prawie
  • nacisk: przede wszystkim, najbardziej godny uwagi, z pewnością

Nie chodzi o to, by używać takich zwrotów na siłę. Warto je stosować ponieważ dzięki nim, łatwiej jest czytać tekst.

6) Jak najmniej strony biernej

A co to właściwie jest?

Według Wikipedii w takim zdaniu, podmiot jest odbiorcą czynności a dopełnienie jest jej wykonawcą. Przykład takich zdań:

„Mleko jest pite przez kota. Kot jest myty przez Karolinę.”

Lepiej jest użyć zdania w stronie czynnej. Te powyższe będą wtedy brzmiały:

„Kot pije mleko. Karolina myje kota.”

W tekście nie powinno być więcej niż 10% zdań w stronie biernej.

Kiedy poprawione zostaną wytyczne, kontrolki widoczności SEO zaświecą się na zielono.

7) Warto również dodać jeden link zewnętrzny

Link podnosi zaufanie do strony z artykułem – może to być link np. do producenta systemu ERP lub do jakiegoś poradnika, w którym dobrze jest opisane jakieś zagadnienie.

 

7) Tłumaczenie

Aby ułatwić tłumaczenie artykułów, należy zaczekać aż do uzyskania ostatecznej wersji artykułu instrukcji a następnie użyć przycisku „Przetłumacz” z opcjami:

„

Następnie pozostaje utworzyć angielskie wersje screenów, zmienić shortcode (element adresu URL do artykułu), oraz zaktualizować wszystkie hyperlinki.