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.