Wytyczne dotyczące stron czasowników i tonuVoice and tone guidelines

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.A wide variety of people including IT Pros and developers read the .NET docs both to learn .NET and to use it in their regular work. Twoim celem jest przygotowywanie doskonałej dokumentacji, która pomoże czytelnikom w osiągnięciu założonego celu.Your goal is to create great documentation that helps the reader on their journey. Nasze wytyczne pomagają w tym.Our guidelines help with that. Nasz przewodnik po stylu zawiera następujące rekomendacje:Our style guide contains the following recommendations:

Używaj konwersacyjnego tonuUse a conversational tone

Poniższy akapit jest napisany w stylu konwersacyjnym.The following paragraph is written in a conversational style. Następny jest w stylu bardziej akademickim.The one that follows it is in a more academic style.

Odpowiedni stylAppropriate style

Chcemy, aby nasza dokumentacja miała konwersacyjny ton.We want our documentation to have a conversational tone. Podczas czytania dowolnego z naszych samouczków lub objaśnień powinno się mieć wrażenie prowadzenia rozmowy z autorem.You should feel as though you are having a conversation with the author as you read any of our tutorials or explanations. Treść powinna mieć nieformalny, konwersacyjny charakter i być bogata w informacje.For you, the experience should be informal, conversational, and informative. Czytelnicy powinni mieć wrażenie, że słuchają autora objaśniającego im pojęcia.Readers should feel as though they are listening to the author explain the concepts to them.

Nieodpowiedni stylInappropriate style

Kontrast między stylem konwersacyjnym i stylem znanym z bardziej akademickiego podejścia do tematów technicznych jest wyraźny.One might see the contrast between a conversational style and the style one finds with more academic treatments of technical topics. 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.Those resources are very useful, but the authors have written those articles in a very different style than our documentation. Czytając czasopismo akademickie, daje się zauważyć zupełnie inny ton i zupełnie inny styl pisania.When one reads an academic journal, one finds a very different tone and a very different style of writing. Czytelnik czuje, że czyta suche sprawozdanie dotyczące zupełnie niestrawnego tematu.One feels that they are reading a dry account of a very dry topic.

Pisz w drugiej osobieWrite in second person

Poniższy akapit jest napisany w drugiej osobie.The following paragraph uses second person. Następny jest napisany przy użyciu trzeciej osoby.The one that follows it uses third person. Pisz w drugiej osobie.Please write in second person.

Odpowiedni stylAppropriate style

Swoje artykuły pisz tak, jakby była to bezpośrednia rozmowa z czytelnikiem.Write your articles as though you are speaking directly to the reader. Często sięgaj po drugą osobę (tak jak w tych dwóch zdaniach).Use second person often (as in these two sentences). Druga osoba nie musi koniecznie oznaczać zwracania się co chwilę per „ty”.2nd person doesn't always mean using the word 'you'. Pisz bezpośrednio do czytelnika.Write directly to the reader. Pisz zdania rozkazujące.Write imperative sentences. Mów czytelnikowi, czego Twoim zdaniem powinien się nauczyć.Tell your reader what you want them to learn.

Nieodpowiedni stylInappropriate style

Autor może również zdecydować się na stosowanie osoby trzeciej.An author could also choose to write in third person. Stosując takie podejście, musi znaleźć jakiś zaimek lub rzeczownik, z użyciem którego będzie zwracał się do czytelnika.In that model, an author must find some pronoun or noun to use when referring to the reader. Czytelnicy często uznają taki styl z trzecią osobą za mniej angażujący i mniej przyjemy w czytaniu.A reader might often find this third person style less engaging and less enjoyable to read.

Używaj strony czynnejUse active voice

Pisz swoje artykuły z użyciem strony czynnej.Write your articles in active voice. Strona czynna oznacza, że podmiot zdania wykonuje akcję (czasownik) w tym zdaniu.Active voice means that the subject of the sentence performs the action (verb) of that sentence. Jest to przeciwieństwo strony biernej, w której zdanie jest ułożone tak, że czynność jest wykonywana względem podmiotu zdania.It contrasts with passive voice, where the sentence is arranged such that the subject of the sentence is acted upon. Porównaj następujące przykłady:Contrast these two examples:

Kompilator przekształcił kod źródłowy w plik wykonywalny.The compiler transformed source code into an executable.

Kod źródłowy został przekształcony w plik wykonywalny przez kompilator.The source code was transformed into an executable by the compiler.

Pierwsze zdanie używa strony czynnej.The first sentence uses active voice. Drugie zdanie zostało napisane z użyciem strony biernej.The second sentence was written in passive voice. (Te dwa zdania to kolejny przykład każdego ze stylów).(Those two sentences provide another example of each style).

Zalecamy stronę czynną, ponieważ jest znacznie czytelniejsza.We recommend active voice because it is more readable. Strona bierna może być trudniejsza w czytaniu.Passive voice can be more difficult to read.

Pisz dla czytelników, którzy mogą mieć ograniczone słownictwoWrite for readers who may have a limited vocabulary

Twoje artykuły trafiają do odbiorców z wielu krajów.You are reaching an international audience with your articles. Dla wielu czytelników język angielski nie jest językiem ojczystym i mogą oni nie znać słownictwa angielskiego, którego używasz.Many of your readers are not native English speakers and may not have the English vocabulary you have.

Z drugiej jednak strony wciąż piszesz do profesjonalistów z branży technicznej.However, you are still writing for technical professionals. Możesz przyjąć, że czytelnicy mają wiedzę z zakresu programowania i opanowali specyficzną dla niego terminologię.You can assume that your readers have programming knowledge and the specific vocabulary for programming terms. Programowanie obiektowe, klasa, obiekt, funkcja i metoda są znanymi terminami.Object Oriented Programming, Class and Object, Function and Method are familiar terms. Nie każdy czytelnik Twoich artykułów ma jednak stopień naukowy z informatyki.However, not everyone reading your articles has a formal computer science degree. Jeśli zdecydujesz się używać terminów takich jak „idempotentność”, będzie trzeba je zdefiniować, na przykład tak:Terms like 'idempotent' probably need to be defined if you use it, for example:

Metoda Close() jest idempotentna, czyli że można wywołać ją wielokrotnie, a efekt będzie taki sam jak przy wywołaniu tylko raz.The Close() method is idempotent, meaning that you can call it multiple times and the effect is the same as if you called it once.

Unikaj czasu przyszłegoAvoid future tense

W niektórych językach innych niż angielski pojęcie czasu przyszłego nie pokrywa się z tym, co znamy z języka angielskiego.In some non-English languages the concept of future tense is not the same as English. Używanie czasu przyszłego może utrudnić czytanie dokumentów.Using future tense can make your documents harder to read. Dodatkowo przy korzystaniu z czasu przyszłego narzucającym się pytaniem jest „kiedy”.Additionally, when using the future tense, the obvious question is when. Jeśli powiesz „Znajomość powłoki PowerShell przyda Ci się”, oczywistym pytaniem dla czytelnika będzie, kiedy mu się przyda.So if you say 'Learning PowerShell will be good for you" - the obvious question for the reader is when will it be good? Zamiast tego powiedz więc lepiej „Znajomość powłoki PowerShell jest przydatna”.Instead, just say "Learning PowerShell is good for you".

Co to jest — i co z tego?What is it - so what?

Zawsze gdy prezentujesz czytelnikowi jakieś nowe pojęcie, najpierw je zdefiniuj, a dopiero wtedy wyjaśnij, dlaczego jest przydatne.Whenever you introduce a new concept to the reader, define the concept and only then explain why it's useful. 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).It's important for reader to understand what something is before they can understand the benefits (or otherwise).