--=REKLAMA=--

Pomoc

Konwencje i styl poradników

Z Joomla!WikiPL

Wersja Zwiastun (dyskusja | edycje) z dnia 15:29, 15 kwi 2009

(różn.) ← poprzednia wersja | przejdź do aktualnej wersji (różn.) | następna wersja → (różn.)

Styl poradnikó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 w przyborniku - 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.
  • Informacje w kolumnach: 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ć 750px. 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 odnośnik, aby...
  • Usuń [Remove]: Kliknij tę ikonę lub odnośnik, 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łowu angielskiego znaku cala,
    • nazwy klawiszy, ikon, opcji ujmuj w nawiasy klamrowe (np. [Enter], [Anuluj], [Edycja]); jeśli stosujesz inne wyróżnienie (pogrubienie, pochylenie), nie ujmuj ich ani w cudzysłów, ani apostrof,
    • przytoczenia, cytaty, teksty komunikatów ujmuj w znaki cudzysłowu, 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 odnośnik, 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łaszcza 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.


Przypisy