Standard tworzenia dokumentacji

Powiązane artykuły

• Jak nagrywać filmy?
• Jak przenosić dokumentację do pliku markdown?

Po co jest ten dokument?

Celem tego dokumentu jest ustalenie jednolitych zasad przygotowania i utrzymywania instrukcji do aplikacji Teneum dla użytkowników końcowych, administratorów i deweloperów.

Odbiorcy instrukcji

1. developer - dokumentacją dla niego jest:

   a. dokument projektu (funkcjonalny i techniczny)

   b. instrukcja administracyjna/developerska

   c. ewentualnie nagrane szkolenie wewnętrzne

2. wdrożeniowiec / administrator IT / administrator obszarowy - dokumentacją dla niego jest wygenerowana przez folianta dokumentacja online na podstawie spisu treści do instrukcji dla administratora/developera

3. użytkownik - dokumentacją dla niego jest wygenerowana przez folianta dokumentacja online na podstawie spisu treści do instrukcji dla użytkownika

Podstawowe zasady

Proces tworzenia i utrzymania dokumentacji

Do standardu Teneum

Założenia:

1. Twórca dokumentacji: tester lub dokumentalista

2. Podstawa do tworzenia dokumentacji: scenariusze testowe, dokument projektu

3. Podczas aktualizacji klienta tematem wytworzonym przez ZRP na repozytorium gita klienta będą wyrównywane również pliki folianta .md i .yml zawierające instrukcje do wersji rozwiązania standardowego

4. Generowanie dokumentacji w pdf - procesy w ITS powinny umożliwić wygenerowanie każdej dokumentacji dostępnej pod jakimś adresem www, także do pliku pdf

Sposób edycji i emisji dokumentacji w ZRP

1. W trakcie realizacji projektu, dokumentację dla wdrożeniowca / administratora oraz dla użytkownika tworzymy w dokumencie google.

2. Jeśli w trakcie projektu potrzebujemy zmodyfikować fragment istniejącej instrukcji, to modyfikujemy pliki md (najlepiej przez przycisk ołówka na stronie dokumentacji i wykonanie commitu zmian na branchu projektu)

3. W trakcie emisji projektu (czyli po pozytywnych testach na branchu projektu) w momencie merga projektu do mastera należy dokonać:

   a. konwersji dokumentu google na pliki *.md - Jak przenosić dokumentację do pliku markdown?

   b. uzupełnić dwa spisy treści w pliku yml (spis treści w instrukcji dla użytkownika oraz spis treści w instrukcji dla wdrożeniowca / administratora)

   c. uzupełnić odnośniki do innych artykułów w dokumentacji, oraz w innych artykułach do tego artykułu

   d. zacommitować te pliki na branchu projektu

4. Testerzy w trakcie ponownych testów na masterze oprócz testowania aplikacji czytają dokumentację i dokonują ostatecznej weryfikacji czy jest dobrze napisana, prawidłowo podzielona i umieszczona w spisie treści.

Sposób edycji i emisji dokumentacji w ZS/ZW dla klienta

Przygotowanie indywidualnego folianta pod klienta

1. klientowi generujemy indywidualną dokumentację w postaci strony WWW, na podstawie źródeł dokumentacji z jego repozytorium. ITS stawia procesy do generowania takiej dokumentacji, jeśli źródła się zmienią.

2. ręcznie (a może automatycznie w przyszłości) do aplikacji klienta do wstążki dodajemy akcje prowadzącą dla jego wersji dokumentacji(branch master repozytorium klienta).

Tworzenie instrukcji do tematów indywidualnych dla klienta

3. Po zakończeniu testów tematu, testerzy spisują instrukcję w formie google doca.

4. Po weryfikacji instrukcji należy dokonać:

   a. konwersji dokumentu google na pliki *.md - Jak przenosić dokumentację do pliku markdown?

   b. uzupełnić dwa spisy treści w pliku yml (spis treści w instrukcji dla użytkownika oraz spis treści w instrukcji dla wdrożeniowca / administratora)

   c. uzupełnić odnośniki do innych artykułów w dokumentacji, oraz w innych artykułach do tego artykułu:

   i.  Jeśli dla klienta modyfikujemy funkcjonalność standardu, to
       tworzymy dodatkowy artykuł do dokumentacji (coś jak
       errata), ale w artykule dotyczącym tego tematu w
       standardzie na początku zaraz po nagłówku doklejamy
       odnośnik do dodatkowego artykułu. W razie aktualizacji
       dokumentacji przy okazji aktualizacji aplikacji nie
       powinno to spowodować ani nielogiczności dokumentacji ani
       konfliktów na plikach.
   
   ii. Jeśli dla klienta robimy nową funkcjonalność to razem z nią
       tworzymy dodatkowe artykuły do dokumentacji, takim samym
       procesem jak przy rozwoju standardu. Dodajemy taki artykuł
       do spisu treści na repozytorium klienta.
   

   d. zacommitować te pliki na branchu zmiany

5. Po weryfikacji umieszcza go na repozytorium klienta i przekazujemy do zapoznania się/weryfikacji przez klienta.

Układ na foliancie

1. Zakładki w górnej linii przeznaczamy na role “Dla użytkownika”, “Dla administratora”

2. Pierwszy poziom spisu treści przeznaczamy na moduły (HID, Produkcja, FK, Personel, Workflow, CRM …)

3. Drugi poziom spisu treści i kolejne przeznaczamy na artykuły w obszarach.

4. Artykuły mogą być długie, gdyż same zawierają własny spis treści. Np edycja kart technologicznych może być jednym artykułem.

Przykładowy spis treści na stronie:

• Dokumentacja użytkownika

  • Handel i Dystrybucja (obszar)

  • Sprzedaż (moduł)

  • Elektroniczne kanały sprzedaży (moduł)

  • … (moduł)

  • Magazyn Wysokiego Składu (obszar)

  • … (moduł)

  • Workflow i Dokumenty (obszar)

  • Workflow (moduł)

  • Dokumenty elektroniczne (moduł)

  • Faktury kosztowe (moduł)

  • Global Quick Search (moduł)

Dokumentacja administratora (wdrożeniowca) powinna mieć spis treści j.w.

Sposób składowania dokumentacji

1. Nie używać znaków specjalnych w nazwach folderów

2. Robimy jeden główny folder “docs” na dokumentację, a w nim spis treści “foliant.yml” - tak jak w technologii

3. Robimy folder “docs/articles” na artykuły. Nie robimy podfolderów do artykułów.

Utrzymanie foliantów

1. Dokumentacja standardu jest generowana per wyemitowana wersja (czyli 5.4, 6.0, 6.1)

   a. każda wersja dokumentacji pochodzi z odpowiedniego brancha wersji

2. Dla klientów ITS we współpracy z opiekunami klientów będzie przygotowywał indywidualną instrukcję klienta generowanego w foliancie z repozytorium klienta na GITcie z brancha MASTER. Proces będzie pilotażowo przygotowywany na kliencie Claudie Design z Damianem Dziubą.

Wytyczne dla redaktorów instrukcji

1. Jeśli dokumentacja dla użytkownika ma artykuł, który posiada analogiczny artykuł dla administratora, to oba artykuły powinny mieć wzajemnie do siebie odnośniki.

   a. W artykułe użytkownika link pod nazwą: “Jak konfigurować?”

   b. W artykule administratora: “Jak używać?”

2. W artykułach nie piszemy, jaka funkcja jest w jakiej wersji, bo to wynika z brancha, na którym jest dany artykuł.

3. Stosujemy czcionki standardowe docsów i formatowania tylko poprzez style nagłówków i zwykłego tekstu(podczas eksportu doca do folianta jest to wykorzystywane do ustrukturyzowania artykułu i budowy spisu treści)

4. Podczas tworzenia screenów korzystamy ze skórki Teneum Blue w wersji 6 lub nowszej. Stosujemy nową wstążkę Neosową, również w wersji 6 lub nowszej.

   a. Screeny wykonujemy na całym ekranie lub jego fragmencie, jeśli jest to konieczne.

   b. Jeśli użytkownik ma wykonać jedną operację, a ma wiele opcji do wyboru, zaznaczamy obszar za pomocą czerwonej ramki.

   c. Jeśli użytkownik wypełnia wiele pól w jednej czynności oznaczamy je kolejno numerami. Kolejne numery, tak samo jak ramki mają być czerwone.

   d. Jeśli okno jest czytelne i nie ma w nim wielu opcji do wyboru to nie oznaczamy go ramką i numerami.

   e. Na screenach nie dodajemy strzałek ani napisów.

   f. Podczas wykonywania operacji i tworzeniu screenów opieramy się na fikcyjnych firmach i danych. Dane które wpisujemy powinny w jakimś stopniu przypominać typ danych, które wpisujemy, np. imię i nazwisko Marian Nowak, a nie Xenia Qwerty.

   g. Daty na screenach

   i.  W screenach nie blurujemy dat ani danych firmowych.
   
   ii. Staramy się tworzyć jak najmniej screenów z datami.
   
   iii. Tworzymy screeny z datą o rok do przodu. Datę zmieniamy w
        aplikacji.
   

5. W dokumentacji technicznej nie stosujemy gifów.

6. Filmy

   a. Filmów w dokumentacji raczej nie chcemy robić, bo się szybko dezaktualizują i trzeba będzie je nagrywać od nowa.

   b. Jeżeli uznamy, że film jest potrzebny to stosujemy się do zasad z poniższego artykułu - Jak nagrywać filmy?

   c. emitujmy filmy na youtube.com na kanał Sente jako filmy niepubliczne bez możliwości komentowania, polubienia, itp. (obecnie dostęp do kanału ma Marcin Smereka)

   d. linkujemy te filmy w artykułach

Treść

1. Forma gramatyczna

   a. Stosujemy formę komunikacji w bezokoliczniku np. Aby przejść dalej należy nacisnąć Zatwierdź.

   b. Forma bezokolicznikowa obowiązuje w przypadku tworzenia dokumentacji dla developera, wdrożeniowca, administratora i użytkownika.

2. Opis okna

   a. Do opisu okna stosujemy wypunktowanie.

   b. Przy wypunktowaniu elementów okna nie stosujemy myślników, ponieważ mogą one się powtarzać w dalszej części tekstu.

   c. Okno opisujemy od góry do dołu, od strony lewej do prawej. Wyjątkiem jest sytuacja w której część funkcji jest zgrupowana, wówczas stosujemy wylistowanie.

3. Opis przycisków i funkcji

   a. Nazwy przycisków i funkcji piszemy kursywą.

   b. Nazwy piszemy zaczynając od wielkiej litery np. Zatwierdź.

4. Kroki użytkownika

   a. Opis kolejnych czynności zapisujemy za pomocą numerowanej listy.

Forma przekazu

W instrukcji wyrażamy się prosto, unikamy skomplikowanych zwrotów i zdań wielokrotnie złożonych. Tekst powinien być klarowny, jednoznaczny i dopasowany do odbiorcy. Podczas tworzenia treści trzymamy się ustalonej formy gramatycznej.

Opis poszczególnych czynności tworzymy w taki sposób, aby użytkownik nie miał problemu z przejściem przez poszczególne etapy instrukcji i wykonywał wszystkie czynności po kolei, z uwzględnieniem “maksymalnej ścieżki” ,tzn. wykonaniem wszystkich możliwych operacji a nie tylko tych podstawowych. Trzymamy się jednej terminologii. Jeden czasownik lub rzeczownik ma oznaczać jedną rzecz lub czynność. Nie używamy synonimów do rzeczowników definiujących elementy aplikacji np. magazynier, operator, użytkownik; lub towar, produkt, przedmiot; lub paczka, nośnik, paleta.