Zależy nam na tym, żeby fachowe poradniki tworzone przez społeczność dhosting.pl były wartościowe i zrozumiałe dla wszystkich osób, które działają w Internecie. Żeby to osiągnąć, stworzyliśmy zestaw zasad dla autorów, dzięki którym tworzenie poradnika będzie przebiegało dużo sprawniej, a sam poradnik stanie się przystępny w odbiorze.
Ogólne zasady
Zadaniem każdego z poradników jest poprowadzenie czytelnika krok po kroku w celu poradzenia sobie z konkretnym wyzwaniem. Oznacza to, że teksty nie mogą zawierać ogólników, muszą być niezwykle szczegółowe oraz pisane językiem zrozumiałym dla jak największego grona odbiorców. Jeśli pojawiają się w nim skomplikowane pojęcia, należy je od razu wyjaśnić. Jeśli rekomendowana jest konkretna aplikacja, należy wyjaśnić, dlaczego akurat ta i podać ewentualne alternatywy. Jako autor wciel się w rolę odbiorcy i nie zakładaj, że to co jest dla ciebie oczywiste, będzie równie oczywiste dla czytelnika. Odbiorca musi otrzymać pełną wiedzę o poruszanym temacie.
Styl poradnika jest równie istotny. Nie twórz tekstu do dokumentacji technicznej. Może być luźniejszy i bardziej przyjazny w odbiorze, ale bez przesady. Unikaj żargonu, żartów zrozumiałych tylko dla konkretnej grupy, a także nawiązań do popkultury czy memów. Jeśli to możliwe, używaj polskich odpowiedników słów, np.:
- nie „button” a „przycisk”;
- nie „input” a „pole tekstowe”.
Do czytelnika zwracaj się w drugiej osobie liczby pojedynczej:
- ŹLE: Teraz należy kliknąć przycisk „Dalej”.
- ŹLE: Proszę kliknąć przycisk „Dalej”.
- ŹLE: Kliknijmy przycisk „Dalej”.
- DOBRZE: Kliknij przycisk „Dalej”.
Poradniki twórz na Google Drive przy pomocy aplikacji Google Docs. Dzięki temu współpraca nad jego ewentualnym dopracowaniem będzie wygodniejsza dla obu stron.
Struktura poradnika
Wstęp fachowego poradnika
Poradnik powinien zaczynać się od wstępu, w którym szczegółowo zostaną zaprezentowane najważniejsze zagadnienia poruszane w poradniku. Wstęp w przypadku fachowych poradników to nie lead – nie musisz ograniczać się w liczbie znaków – kluczowe jest przekazanie wszystkich najważniejszych informacji.
Przykład:
Wtyczka do WordPressa to nic innego jak fragment kodu, którego głównym zadaniem jest rozszerzenie podstawowych funkcji aplikacji. W większości paneli administracyjnych funkcjonuje koncepcja modułów, które stanowią swego rodzaju osobne organizmy implementujące własne procedury, klasy, metody, interfejsy czy funkcje. W tym przypadku kluczowe jest słowo „osobne”, ponieważ wtyczki są niezależne i wymienne. Można je włączać oraz wyłączać w dowolnym momencie.
Przy ich pomocy możesz nadpisywać i zmieniać działanie całego WordPressa – zarówno od strony back-endu jak i front-endu. Ta koncepcja ma swoje źródło w programowaniu obiektowym, w którym program stanowi zbiór obiektów, które – aby wykonać dane zadanie – komunikują się między sobą. Sam WordPress jest na tyle elastyczny, że może przyjąć nawet najbardziej nietuzinkowe koncepcje, a twórcę ogranicza jedynie wyobraźnia i własne umiejętności.
W ramach poradnika stworzysz wtyczkę pozwalająca na dodanie logotypów klientów w formie karuzeli, która będzie wyświetlała się w menu panelu administracyjnego WordPressa, pozwalała na dzielenie klientów na kategorie, dodanie nazwy firm czy logotypu. Następnie wtyczka pozwoli wywołać karuzelę (w całości lub tylko z wybranych kategorii) na danej stronie przy użyciu shortcode.
Jeśli jest to możliwe, napisz, jaki efekt przyniesienie wdrożenie instrukcji z poradnika, np.:
Tak prezentuje się końcowy efekt w panelu WordPressa:
Poniżej natomiast znajduje się wygląd strony po wywołaniu wtyczki:
Na końcu artykułu znajdziesz do pobrania paczkę z wtyczką gotową do uruchomienia w swoim WordPressie.
Przykład drugi:
Czego się nauczysz?
Dzięki poradnikowi dowiesz się, w jaki sposób wykonać stronę opartą o WordPressa, która będzie dostępna w kilku językach, zachowując niezależność każdej wersji językowej. W skrócie – proces będzie polegał na sklonowaniu już przygotowanej wcześniej witryny i przetłumaczeniu jej na docelową wersję językową.
Efektem takiej operacji będzie wielojęzyczna strona bez użycia wtyczek.
Jeśli do ukończenia poradnika wymagane jest konkretne oprogramowanie lub wiedza, napisz o tym.
Przykład:
Do kogo kierowany jest ten poradnik?
- Omawiane zagadnienia wymagają wcześniejszej styczności i doświadczenia w programowaniu w języku PHP i podstawowej znajomości JavaScript.
- Niezbędna jest również podstawowa znajomość WordPress Hooks (element Plugin API WordPressa).
- Znajomość MySQL i struktury bazy danych WordPressa.
- Znajomość HTML oraz CSS.
Czego potrzebujesz?
- Edytora kodu źródłowego. Do stworzenia poradnika wykorzystywałem Visual Studio Code autorstwa Microsoftu dystrybuowany na licencji MIT, który można pobrać za darmo ze strony producenta.
- Klienta FTP. Osobiście korzystam z FileZilla, który jest dostępny do pobrania za darmo na stronie producenta.
- Cierpliwości, chęci, wyobraźni i czasu.
Przykład drugi:
Czego potrzebujesz?
Żeby ukończyć poradnik, twoja strona musi działać w oparciu o CMS WordPress. Dodatkowo będziesz potrzebował:
- Tłumaczenia strony na wybrane języki.
- Wtyczki do klonowania (w poradniku wykorzystuję darmową: NS Cloner – Site Copier).
- WordPress Multisite Network (sieć witryn w WordPressie).
Instrukcja krok po kroku
Kolejnym elementem struktury fachowego poradnika jest instrukcja wykonania opisana krok po kroku. Jeśli tematy poruszane w poradniku wymagają szczegółowego omówienia, każdy punkt traktuj jako jeden krok i oznaczaj go stylem „Nagłówek 2”.
Przykład:
Krok 1 – Struktura i tworzenie pliku głównego
Wewnątrz folderu klienci utwórz plik główny clients-carousel.php, a następnie dodaj w nim pozostałe katalogi tak, żeby zachować poniższą strukturę.
/klienci
/includes
/public
/css
/js
clients-carousel.php
Cała wtyczka będzie utrzymana w powyższej prostej formie na potrzeby poradnika. Dzięki temu od razu będzie widać, co z czego dokładnie wynika bez rozbijania późniejszych elementów na zbyt dużą liczbę klas czy funkcji.
Plik główny (clients-carousel.php) jest podstawowym elementem, dzięki któremu WordPress rozpoznaje wtyczkę. Jest to zawsze plik PHP z zakomentowanymi informacjami.
Zakończenie poradnika
Zakończenie powinno podsumować to, czego nauczył się czytelnik. Możesz podpowiedzieć również, jakie dalsze kroki może podjąć, żeby jeszcze lepiej przyswoić daną tematykę.
Przykład:
Podsumowanie
Tak jak widzisz, do stworzenia wielojęzycznej strony nie potrzebujesz żadnej wtyczki. Ta do klonowania została użyta, by ułatwić proces. Po przetłumaczeniu witryny możesz ją bez obaw wyłączyć lub usunąć.
Ta proste metoda posiada wiele zalet. Największą z nich jest niezależność każdego z wariantów strony. Możesz dostosować menu, podstrony i widgety dla każdego języka całkowicie niezależnie.
Design również może się różnić, a to istotne, ponieważ niektóre wyrażenia po przetłumaczeniu mogą być o wiele dłuższe. Wtedy istnieje możliwość, że litery nie zmieszczą się w polu do tego przeznaczonym albo odwrotnie – tekstu będzie za mało, żeby dobrze wyglądał na tle wielkiego pola. Dobrym przykładem jest zdanie:
All rights reserved
Tłumacząc na japoński otrzymamy:
当サイト内のすべてのコンテンツは著作権法により保護されています。
Dlatego niezależność między wersjami językowi jest tak istotna.
Zrzuty ekranu i formatowanie
Ilustracje oraz zrzuty ekranu zamieszczaj w Google Docs przy pomocy „Wstaw obraz”. Musisz dołączyć je również spakowane do .zip w wiadomości mailowej.
Wszystkie grafiki dołączone do poradnika muszą być wykonane przez jego autora. Licencja zdjęć pobranych z zewnętrznych źródeł musi dawać możliwość wykorzystania komercyjnego. Jeśli wymagane jest oznaczenie autorstwa – koniecznie napisz o tym w komentarzu do zdjęcia. Preferowane są grafiki wykonane przez autora poradnika lub takie, które nie wymagają oznaczenia autorstwa.
Jeśli istnieje uzasadnienie ich użycia, w poradniku mogą znaleźć się również GIFy oraz filmy.
Formatowaniem treści przed publikacją poradnika zajmuje się pracownik dhosting.pl. W celu sprawnej pracy osoby odpowiedzialnej za publikację, w Google Docs używaj stylów akapitów, list numerowych oraz list punktowanych.