Podręczniki

Podręczniki Joomla! zapisywane są w formacie DocBook.

DocBook to zestaw standardów i narzędzi pozwalających uzyskać z jednego tekstu źródłowego wersje dokumentu w różnych formatach: TXT, HTML, PDF, XML, DOC, PS.

Elementy DocBooka tworzą hierarchię: na jej szczycie jest element SET (zestaw książek), poniżej BOOK (książka). następnie PART (część, tom), niżej równorzędne CHAPTER (rozdział) i ARTICLE (artykuł), w których znajdować się mogą takie elementy, jak: SECTION, SECT1, SECT2 (sekcje) tudzież PARA (akapit) i inne. Obok rozdziałów (chapter) w standardzie DocBook znajdujemy m.in. elementy REFERENCES (odniesienia), APPENDIX (aneksy, dodatki). Tworząc podręczniki o Joomla!, korzystamy z uproszczonego standardu DocBook.

Do tworzenia podręczników wykorzystujemy element BOOK i CHAPTER (np. w podręczniku instalacji) lub REFERENCES (np. w podręczniku administratora). Do budowy wewnętrznej hierarchii rozdziałów wykorzystujemy elementy SECT1, SECT2, itd.

Dodatkowe szczegóły znajdziesz w poniższym opracowaniu
Stosowanie edytora XMLMind

Styl dokumentów

Praca nad dokumentem wchodzącym w skład podręcznika jest zwykle wieloetapowa. Zanim przybierze ostateczny kształt, możliwe jest opublikowanie wersji roboczej. Zarówno w wersji roboczej, jak i ostatecznej stosujemy pewne konwencje zapewniające jednolity styl dokumentów. Zastosuj się do poniższych wskazówek:

Elementy opisu

Stosuj standardowe elementy i nazewnictwo elementów opisu:

• Informacja wstępna: W pierwszych zdaniach poinformuj o podstawowym celu dokumentu lub podstawowych funkcjach, jakie użytkownik realizuje, korzystając z elementu Joomla, któremu poświęcony jest dokument.
• Ikony paska narzędzi - możliwe działania : jeśli opisujesz ekran panelu administracyjnego, wypisz dostępne opcje w pasku narzędzi i wskaż funkcję każdej z ikon i odsyłaczy. Pożądane jest zilustrowanie każdego odniesienia do grafiki ikony lub zilustrowanie całego fragmentu zrzutem ekranu zawierającym dostępne ikony.
  
• Kolumny wykazu: jeśli opisujesz ekran, na którym znajduje się wykaz elementów w tabeli, wypisz nazwy kolejnych kolumn i opisz zawarte w nich informacje. Jeśli możliwe są jakieś działania na elementach tabeli (np. gdy nazwa elementu jest odnośnikim, gdy kliknięcie w ikonę powoduje zmianę stanu) - opisz to działanie. Pożądane jest zilustrowanie tego fragmentu zrzutem ekranu zawierającym fragment tabeli, wzbogaconym o wskazanie najważniejszych możliwych działań.
• Pola edycji: jeśli opisujesz ekran edycji szczegółów, wypisz nazwy wszystkich elementów i posługując się trybem rozkazującym (czasowniki ’wpisz’, ’określ’, ’ustaw’) poinstruuj użytkownika, w jaki sposób powinien edytować detale informacji. Pożądane jest zilustrowanie tego fragmentu zrzutem lub zrzutami ekranu zawierającymi opisywane elementy, wzbogaconymi o wskazanie istotnych czynności, zwłaszcza odbiegających od typowych dla danego rodzaju formularza.
• Uwagi: Jeśli opatrujesz instrukcję uwagą, ostrzeżeniem, poradą - wyróżnij ten element nagłówkiem (np. Uwaga:, Porada:) i zamieść jej tekst w tym samym lub nowym akapicie.
  

Ilustracje:

Jeśli ilustrujesz dokument, przygotuj zoptymalizowaną grafikę w formacie JPG lub PNG. Szerokość obrazków nie powinna przekraczać 550px. Stosuj w miarę możności standarowe szerokości obrazków: 200 px, 275px, 400 px, 550px. 

Akapit czy lista punktowana

Treść ujmuj w krótkie akapity, zgodnie z zasadą "5 plus-minus 2". Innymi słowy 5-6 wierszy w akapicie to w zasadzie górna granica. Oczywiście, jeśli zdarzy się akapit 7-wersowy, to nic złego się nie stanie. Dłuższe akapity podziel w najodpowiedniejszym miejscu na dwa.

Jeśli tylko możliwe jest ujęcie treści w punktach (wszelkie wykazy, opisu kolejnych czynności) - skorzystaj z tej możliwości. Dla użytkownika taki tekst jest czytelniejszy.

W wersji roboczej możesz ująć wykaz w jednnym akapicie, przełamując wiersz po każdym elemencie listy. Szczególnie w przypadkach, gdy pierwszy wyraz wskazuje opcję. Wyróżnij ten pierwszy wyraz czy pierwsze wyrażenie pismem pochyłym lub pogrubionym, np.

Edytuj [Edit]: Kliknij tę ikonę lub odsyłacz, aby...
Usuń [Remove]: Kliknij tę ikonę lub odsyłacz, aby...

Inne konwencje

1. Wielkie i małe litery:
   • używaj wielkich liter rozpoczynając opis opcji (jak w przykładzie powyżej); jeśli Ci to sprawia trudność, możesz używać - ale konsekwentnie w całym dokumencie - małych liter,
   • używaj wielkich liter zawsze, gdy przywołujesz nazwę własną składnika (komponentu, modułu, dodatku), a także ikony, klawisza (np. ’Enter’, ’Anuluj’)
   • używaj małych liter, którzy przywołujesz nazwę w potocznym znaczeniu.
   • słowa: ’e-mail’, ’webmaster’, ’administrator’, ’główny administrator’, ’witryna’, ’strona WWW’ pisz z zasady małymi literami, chyba, że używasz ich na początku zdania bądź jako ważnych w kontekście opisu nazw własnych,
   • słowo ’Internet’ , a także zaimki ’Ty’, ’Ci’, ’Tobie’ pisz zawsze z wielkiej litery.
2. Apostrofy i cudzysłowy:
   • używaj jako cudzysłowia angielskiego znaku cala,
   • nazwy klawiszy, ikon, opcji ujmuj w pojedyncze apostrofy  (np. ’Enter’, ’Anuluj’, ’Edycja’); jeśli stosujesz inne wyróżnienie (pogrubienie, pochylenie), nie ujmuj ich ani w cudzysłów, ani apostrof,
   • przytoczenia, czytaty, teksty komunikatów ujmuj w znaki cudzysłowia, np. "Nowe elementy zostały zapisane", nie stosuj w takich przypadkach pochyłej czcionki, możesz ująć je w znacznik z klasą stylu "quote" lub "cytat"
3. Typowe wyrażenia:
   • na działania myszką wskazuj zwrotami: kliknij tę ikonę lub odsyłacz, zaznacz pole wyboru;
     
   • na działania klawiatury wskazuj zwrotami naciśnij klawisz, naciśnij klawisze CTRL+SHIFT,
   • wskazując na opcje, ikony, konkretne składniki Joomla! (komponenty, dodatki) używaj polskiego nazewnictwa, ale - przywołując taką nazwę zwłąszcza po raz pierwszy w dokumencie, opatrz ją oryginalnym angielskim odpowiednikiem w nawiasach kwadratowych, np.: Ustawienia globalne [Global Configuration]; możesz zastosować tę zasadę także w stosunku do niektórych komunikatów, jeśli doświadczenie podpowiada Ci, że nie zostaną one najprawdopodobniej spolonizowane.

Ekrany Pomocy

Ekrany Pomocy zapisuj jako odrębne dokumenty. Jeśli opracowujesz instrukcję czy poradnik w formacie DocBooka - każdy fragment, który ma być lub może być ekranem Pomocy ujmuj w element SECTION lub SECT1, SECT2, itd. W przypadku, gdy system Pomocy Joomla! korzysta z obszernego dokumentu, tytuły sekcji są wykorzystywane jako odniesienia w indeksie Pomocy.

Duplikaty sekcji - zapisane w formacie XML - mogą być umieszczone w katalogu /help dystrybucji Joomla. Aby Joomla! prawidłowo je przetwarzało przy pomocy arkusza stylów CSS, dodaj w pliku następujące linie:

 
<?xml version='1.0'; encoding='ISO-8859-2'?>
<?xml-stylesheet href='css/docbook.css' type='text/css'?>

Hiperłącza (linki) w plikach XML

DocBook korzysta ze znacznika unlink, który nie jest przetwarzany przez pliki css zgodnie z konwencją odsyłaczy. Konieczna jest więc nieznaczna ręczna ich modyfikacja:

Dodaj w głównym [root] elemencie Twojego pliku XML odwołanie do przestrzeni nazw xhtml:

Użyj następujących wyrażeń regularnych w swoim edytorze, aby dokonać niezbędnej modyfikacji:

Po zmianie Twoje hiperłącze powinno wyglądać np. tak: