Wytyczne dotyczące stron czasowników i tonu

Dokumentację platformy .NET czyta wielu ludzi, w tym informatycy i deweloperzy. Uczą się z nich platformy .NET i dowiadują, jak korzystać z niej w codziennej pracy. Twoim celem jest przygotowywanie doskonałej dokumentacji, która pomoże czytelnikom w osiągnięciu założonego celu. Nasze wytyczne pomagają w tym. Nasz przewodnik po stylu zawiera następujące rekomendacje:

Używaj konwersacyjnego tonu

Poniższy akapit jest napisany w stylu konwersacyjnym. Następny jest w stylu bardziej akademickim.

Odpowiedni styl

Chcemy, aby nasza dokumentacja miała konwersacyjny ton. Podczas czytania dowolnego z naszych samouczków lub objaśnień powinno się mieć wrażenie prowadzenia rozmowy z autorem. Treść powinna mieć nieformalny, konwersacyjny charakter i być bogata w informacje. Czytelnicy powinni mieć wrażenie, że słuchają autora objaśniającego im pojęcia.

Nieodpowiedni styl

Kontrast między stylem konwersacyjnym i stylem znanym z bardziej akademickiego podejścia do tematów technicznych jest wyraźny. Zasoby drugiego rodzaju są bardzo pomocne, ale ich autorzy pisali je z użyciem stylu znacznie różniącego się od tego zastosowanego w naszej dokumentacji. Czytając czasopismo akademickie, daje się zauważyć zupełnie inny ton i zupełnie inny styl pisania. Czytelnik czuje, że czyta suche sprawozdanie dotyczące zupełnie niestrawnego tematu.

Pisz w drugiej osobie

Poniższy akapit jest napisany w drugiej osobie. Następny jest napisany przy użyciu trzeciej osoby. Pisz w drugiej osobie.

Odpowiedni styl

Swoje artykuły pisz tak, jakby była to bezpośrednia rozmowa z czytelnikiem. Często sięgaj po drugą osobę (tak jak w tych dwóch zdaniach). Druga osoba nie musi koniecznie oznaczać zwracania się co chwilę per „ty”. Pisz bezpośrednio do czytelnika. Pisz zdania rozkazujące. Mów czytelnikowi, czego Twoim zdaniem powinien się nauczyć.

Nieodpowiedni styl

Autor może również zdecydować się na stosowanie osoby trzeciej. Stosując takie podejście, musi znaleźć jakiś zaimek lub rzeczownik, z użyciem którego będzie zwracał się do czytelnika. Czytelnicy często uznają taki styl z trzecią osobą za mniej angażujący i mniej przyjemy w czytaniu.

Używaj strony czynnej

Pisz swoje artykuły z użyciem strony czynnej. Strona czynna oznacza, że podmiot zdania wykonuje akcję (czasownik) w tym zdaniu. Jest to przeciwieństwo strony biernej, w której zdanie jest ułożone tak, że czynność jest wykonywana względem podmiotu zdania. Porównaj następujące przykłady:

Kompilator przekształcił kod źródłowy w plik wykonywalny.

Kod źródłowy został przekształcony w plik wykonywalny przez kompilator.

Pierwsze zdanie używa strony czynnej. Drugie zdanie zostało napisane z użyciem strony biernej. (Te dwa zdania to kolejny przykład każdego ze stylów).

Zalecamy stronę czynną, ponieważ jest znacznie czytelniejsza. Strona bierna może być trudniejsza w czytaniu.

Pisz dla czytelników, którzy mogą mieć ograniczone słownictwo

Twoje artykuły trafiają do odbiorców z wielu krajów. Dla wielu czytelników język angielski nie jest językiem ojczystym i mogą oni nie znać słownictwa angielskiego, którego używasz.

Z drugiej jednak strony wciąż piszesz do profesjonalistów z branży technicznej. Możesz przyjąć, że czytelnicy mają wiedzę z zakresu programowania i opanowali specyficzną dla niego terminologię. Programowanie obiektowe, klasa, obiekt, funkcja i metoda są znanymi terminami. Nie każdy czytelnik Twoich artykułów ma jednak stopień naukowy z informatyki. Jeśli zdecydujesz się używać terminów takich jak „idempotentność”, będzie trzeba je zdefiniować, na przykład tak:

Metoda Close() jest idempotentna, czyli że można wywołać ją wielokrotnie, a efekt będzie taki sam jak przy wywołaniu tylko raz.

Unikaj czasu przyszłego

W niektórych językach innych niż angielski pojęcie czasu przyszłego nie pokrywa się z tym, co znamy z języka angielskiego. Używanie czasu przyszłego może utrudnić czytanie dokumentów. Dodatkowo przy korzystaniu z czasu przyszłego narzucającym się pytaniem jest „kiedy”. Jeśli powiesz „Znajomość powłoki PowerShell przyda Ci się”, oczywistym pytaniem dla czytelnika będzie, kiedy mu się przyda. Zamiast tego powiedz więc lepiej „Znajomość powłoki PowerShell jest przydatna”.

Co to jest — i co z tego?

Zawsze gdy prezentujesz czytelnikowi jakieś nowe pojęcie, najpierw je zdefiniuj, a dopiero wtedy wyjaśnij, dlaczego jest przydatne. Dla czytelnika ważne jest, aby zrozumiał, czym coś jest, zanim będzie w stanie zrozumieć wynikające z tego korzyści (lub tego wady).