Wprowadzenie
Struktura nowo powstających haseł należących do działu dokumentacji powinna być zgodna z przyjętymi i jednocześnie obowiązującymi standardami. Aktualny standard określający zalecaną strukturę dla zamieszczanych haseł w dokumentacji został opisany w poprzednim rozdziale. W niniejszym rozdziale zostaną omówione pozostałe aspekty związane tworzeniem czytelnej i spójnej (z punktu widzenia redakcyjnego) dokumentacji.
Praca z wiarygodnymi materiałami
Rozpoczynając pracę nad nowym hasłem kluczowym jest, aby tworzone materiały powstawały w oparciu o wiarygodne źródło informacji. W pełni wiarygodnymi źródłami informacji są oficjalne anglojęzyczne dokumentacje, dostarczane przez twórców danych bibliotek. Jeżeli opisujesz np. narzędzia należące do biblioteki WinAPI to opieraj się o wiedzę zawartą w dokumentacji MSDN. Jeżeli opisujesz bibliotekę do obsługi XML to korzystaj z dokumentacji, jaka jest oficjalnie z nią dystrybuowana.
Standardowe biblioteki C/C++
Jeżeli podejmujesz się opracowywania haseł należących do standardu C lub C++ to postaraj się, aby hasło zostało opracowane wyczerpująco w oparciu o dokumentację MSDN lub
http://en.cppreference.com/ lub
http://www.cplusplus.com/reference/.
Własne doświadczenia
Jeżeli masz doświadczenie w pracy z daną biblioteką to warto abyś się tą wiedzą umiejętnie dzielił. W oficjalnych dokumentacjach wielu bibliotekom brakuje precyzyjnych sformułowań i opisów co dana funkcja tak na prawdę robi oraz jak się zachowuje w danych przypadkach. Takie informacje są cenne, więc zaleca się rozbudowywać treść dokumentacji o rzeczy, które nie zostały wyjaśnione, a wyjaśnione być powinny.
Pamiętaj jednak aby nie opracowywać haseł tylko i wyłącznie na podstawie własnej wiedzy. Hasła powinny być opracowane wyczerpująco, tj. czytelnik powinien mieć gwarancję, że po przeczytaniu danego pojęcia będzie pewien, że zdobył informacje co najmniej tak wyczerpujące jak w oficjalnej dokumentacji danej biblioteki (a miejscami nawet i lepsze).
Przykłady
W wielu przypadkach hasła w dokumentacji nie zawierają przykładów. Dobrze przemyślany przykład ułatwia czytelnikowi pracę z dokumentacją. Tworząc przykłady pamiętaj, aby były one krótkie. Przykładowy kod powinien w maksymalnym stopniu koncentrować się na prezentacji działania omawianego hasła, a nie prezentować w pełni funkcjonalne rozwiązanie, które często wymaga kilkudziesięciu dodatkowych wierszy. Krótki przykład to dobry przykład. Pamiętaj o tym.
Struktura dokumentu, a sekcje
Rekomendowana struktura haseł dla działu dokumentacji jest bardzo długa. Pamiętaj aby zamieszczać tylko te sekcje, które występują w danym haśle. Jeżeli opisujesz np. zwykłą funkcję to nie ma potrzeby aby w haśle znalazły się sekcje takie jak "Parametry szablonu" czy też "Parametry makra". Jeżeli funkcja nie zwraca wartości to również nie ma sensu aby zamieszczać sekcję "Zwracana wartość". Programista widząc deklarację
wie, że dana funkcja niczego nie zwróci, więc nie ma potrzeby akcentowania tego typu informacji. Sekcje w dokumencie należy umieszczać tylko te, w których można przekazać czytelnikowi użyteczne i praktyczne informacje. Pamiętaj, że czytelnik docenia treść, która zawiera dużo użytecznych informacji. Pamiętaj również, aby sekcje były zamieszczane zawsze w tej samej kolejności, w jakiej zostały wymienione w dokumencie przedstawiającym przykładową strukturę haseł.
Opisywanie haseł, a zagadnienia powiązane
Pamiętaj aby w danym haśle
nie pisać o innych hasłach. Dane hasło powinno zawierać informacje tylko i wyłącznie takie, które bezpośrednio jego dotyczą. Jeżeli istnieje hasło powiązane, to dodaj je w sekcji "Zagadnienia powiązane". Czytelnik jeżeli będzie chciał doczytać o innym rozwiązaniu to je doczyta pod hasłem powiązanym.
Sekcja zawierająca składnię
W sekcji zawierającej składnię kluczowym jest, aby zawierać informację jaki nagłówek należy dołączyć aby dane narzędzie było widoczne w kodzie pisanego przez czytelnika programu. Informację tą zamieszczamy tak samo jak wygląda dołączanie plików z poziomu kodu w C++, czyli:
Narzędzia umieszczone w przestrzeni nazw
Jeżeli opisujesz narzędzie, które jest umieszczone w przestrzeni nazw - zapisz tą informację zgodnie ze składnią języka C++. Przykład:
#include <boost/array.hpp>
namespace boost
{
template < class T, std::size_t N >
class array
{
};
}
Czytelnik wówczas wie, że omawiane zagadnienie jest umieszczone w przestrzeni nazw, więc nie będzie miał problemów z ewentualnym użyciem danego narzędzia.
Nie używaj w przykładach using namespace ...
Odradza się używania zapisu
using namespace...;
w przykładowych programach. Zapis ten jest zbędną linijką kodu, a ponadto czytelnik kopiując fragment kodu prawdopodobnie będzie musiał go poprawiać tak, aby jego działanie nie wymagało wstawiania do kodu wspomnianego zapisu.
Odstępy między sekcjami
Podczas formatowania treści dokumentu pamiętaj, aby nie wstawiać niepotrzebnych pustych wierszy przed znacznikami [h1], [h2] oraz [h3]. Licz się z tym, że niektórzy użytkownicy mają potrzebę wydrukowania niektórych haseł znajdujących się w dokumentacji, a każdy zbędny enter może przyczynić się do konieczności wydrukowania jednej strony więcej niż by użytkownik sobie tego życzył. Pamiętaj również, że style zdefiniowane na łamach serwisu same z siebie zapewniają odpowiednie odstępy po różnych znacznikach. Nie ma więc potrzeby abyś ręcznie wymuszał inne formatowanie niż ogólno przyjęty standard.
Tłumacz tekst rozsądnie
Jeżeli chcesz koniecznie tłumaczyć tekst i nie wychodzi Ci pisanie własnymi słowami tego co zostało opisane w innym języku to staraj się tłumaczyć tak, aby dało się bez zastanawiania rozumieć sens każdego zdania. Automatyczne tłumaczenie zdań za pomocą translatora Google bardzo często nie jest satysfakcjonujące, więc tego typu narzędzia należy traktować w kategoriach wsparcia procesu tłumaczenia, a nie w kategoriach akceptowalnego tłumaczenia.
Używaj właściwej terminologii
Pamiętaj, aby stosować właściwą terminologię w każdym haśle, które tworzysz. Argumenty metod i funkcji nazywaj argumentami, a nie np. parametrami. Dobieranie właściwych słów i terminów ułatwia zrozumienie czytanego tekstu.
Zakładaj, że czytelnik zna podstawy
Opisując dane hasło musisz zakładać, że dla czytelnika bariery nie stanowi ani techniczny język, ani składnia języka programowania. Dzięki temu możesz skoncentrować się na opisie danego narzędzia (np. funkcji), a nie na opisywaniu podstaw programowania. Pamiętaj, że książki oraz kursy mają tłumaczyć podstawy, a hasło w dokumentacji ma opisywać tylko i wyłącznie omawiane narzędzie.
Weryfikuj swoją pracę
Jeżeli już opracujesz hasło, poświęć czas na jego weryfikację. Wciel się w osobę trzecią, która nie ma tej samej wiedzy co Ty oraz nie wie co było napisane w oryginalnym źródle. Taki sposób czytania pozwala tworzyć treść bardziej przystępną dla przeciętnego czytelnika. Pamiętaj też, że za kilka miesięcy być może sam będziesz miał potrzebę przeczytania hasła, które sam opracowałeś. Opracuj więc hasło tak, abyś po przeczytaniu jego posiadał wiedzę podobną do tej, którą zdobyłeś podczas opracowywania danego hasła.
Jakość, a nie ilość
No i najważniejsze... jakość haseł jest znacznie ważniejsza niż ich ilość. Jedno dobrze opracowane hasło jest dużo więcej warte dla czytelnika niż posiadanie opisu kilkunastu haseł marnej jakości. Tylko i wyłącznie jakość jest w stanie przekonać czytelnika do korzystania z polskiej dokumentacji, więc staraj się opracowywać hasła dokładnie, kompletnie i rzetelnie.