Styl i głos platformy Microsoft Learn — szybki start

Ten przewodnik Szybki start to krótki przewodnik po pisaniu zawartości technicznej do publikacji w witrynie Microsoft Learn. Te wskazówki odnoszą się do zarówno do tworzenia nowej dokumentacji, jak i aktualizowania istniejącej.

Najlepsze rozwiązania:

• Sprawdzaj pisownię i gramatykę w swoich artykułach, nawet jeśli trzeba je w tym celu skopiować i wkleić do programu Microsoft Word.
• Używaj swobodnego i przyjaznego tonu — jak w rozmowie z inną osobą.
• Używaj prostych zdań. Dzięki prostym do zrozumienia zdaniom czytelnik może szybko rozpocząć korzystanie z udostępnionych wskazówek.

Korzystaj z zasad firmy Microsoft dotyczących tonu

Dążymy do przestrzegania tych zasad podczas pisania zawartości technicznej dla usługi Microsoft Learn. Być może nie zawsze nam się to udaje, ale musimy próbować.

• Skoncentruj się na celu: klienci mają na uwadze konkretny cel, gdy odwołują się do naszej dokumentacji. Zanim rozpoczniesz pisanie, jasno określ, kim jest klient i jakie próbuje wykonać zadanie. Następnie napisz artykuł, który pomoże temu konkretnemu klientowi wykonać to konkretne zadanie.
• Używaj zwykłego słownictwa: spróbuj używać języka naturalnego i słów, których używają Twoi klienci. Zawartość powinna być mniej formalna, ale nie mniej techniczna. Dawaj przykłady opisujące nowe pojęcia.
• Pisz zwięźle: nie marnuj słów. Wykaż się zdecydowaniem i nie używaj dodatkowych słów lub wielu kwalifikatorów. Dbaj, aby zdania były krótkie i zwięzłe. W artykule trzymaj się wybranego tematu. Jeśli zadanie ma kwalifikator, umieść go na początku zdania lub akapitu. Ogranicz również do minimum liczbę przypisów. Stosuj zrzuty ekranów, jeśli pozwoli to na ograniczenie liczby słów.
• Napisz swój artykuł tak, aby był łatwy do przeglądania: większość ważnych treści umieść na początku. Używaj sekcji, aby dzielić długie procedury na łatwiejsze do zrozumienia grupy kroków. (Procedury z ponad 12 krokami są prawdopodobnie zbyt długie). Użyj zrzutu ekranu, gdy zwiększa przejrzystość.
• Wykaż się empatią: stosuj w artykule wspierający ton i do minimum ogranicz zastrzeżenia. Uczciwie wskaż obszary, które mogą być trudniejsze dla klientów. Upewnij się, że artykuł koncentruje się na tym, co jest ważne dla klienta. Nie dawaj technicznego wykładu.

Rozważ lokalizację i tłumaczenie maszynowe

Nasze artykuły techniczne są przetłumaczone na wiele języków, a niektóre zostały zmodyfikowane na potrzeby poszczególnych rynków lub lokalizacji geograficznych. Podczas czytania artykułów technicznych w Internecie użytkownicy mogą korzystać również z funkcji tłumaczenia maszynowego. Dlatego podczas pisania miej na uwadze następujące wskazówki:

• Upewnij się, że artykuł nie zawiera błędów gramatycznych, ortograficznych ani interpunkcyjnych: tego z założenia powinniśmy przestrzegać. Niektóre edytory języka Markdown, np. Markdown Pad 2.0, mają wbudowany podstawowy moduł sprawdzania pisowni, jednak dobrą praktyką jest wklejanie treści artykułu (w postaci HTML) do edytora Word, który dysponuje bardziej zaawansowanym modułem sprawdzania pisowni i poprawności gramatycznej.
• Niech zdania będą możliwie krótkie: zdania złożone i łańcuchy zdań podrzędnych utrudniają tłumaczenie. Podziel zdania na mniej złożone, jeśli nie powoduje to powtarzania treści lub nienaturalnego brzmienia. Nie chcemy artykułów napisanych w nienaturalnym języku.
• Używaj prostej i konsekwentnej konstrukcji zdań: zachowanie konsekwencji ułatwia tłumaczenie. Unikaj wtrąceń i dygresji i staraj się umieszczać podmiot możliwie blisko początku zdania. Zapoznaj się z kilkoma opublikowanymi artykułami. Jeśli artykuł ma przyjazny styl i łatwo się go czyta, wzoruj się na nim.
• Konsekwentnie używaj słownictwa i wielkich liter: ponownie kluczowa jest konsekwencja. Nie pisz słowa wielką literą, jeśli nie stoi ono na początku zdania lub nie jest nazwą własną.
• Wstawiaj „małe słówka”: słowa, które w języku angielskim wydają nam się mało znaczące, ponieważ rozumiemy je z kontekstu (takie jak „a”, „the”, „that” lub „is”), mają kluczowe znaczenie podczas tłumaczenia maszynowego. Upewnij się, że ich nie pomijasz.

Inne zagadnienia związane ze stylem i tonem

• Nie rozdzielaj kroków komentarzami lub dygresjami.
• W przypadku kroków zawierających fragmenty kodu dodatkowe informacje dotyczące kroku wprowadź do kodu w formie komentarza. Pozwala to na zmniejszenie ilości tekstu, który trzeba przeczytać. Kluczowe informacje trafiają do projektu kodu, gdzie będą później przypominać, jakie jest zastosowanie danego kodu.
• We wszystkich tytułach i nagłówkach stosuj wielkość liter jak w zdaniach.
• Używaj zwrotu „sign in”, a nie „log in”.
• Więcej wytycznych można znaleźć w przewodniku redakcyjno-stylistycznym firmy Microsoft.

Dokumentacja lokalizowana

• Jeśli współtworzysz zlokalizowaną dokumentację, zapoznaj się z odwołaniami do globalizacji.
• W celu uzyskania wskazówek odnośnie do lokalizacji, informacji dotyczących stylu i jego użycia w publikacjach technicznych oraz informacji dotyczących formatów danych charakterystycznych dla danego rynku pobierz Przewodnik stylistyczny w swoim języku.
• Odwiedź witrynę Terminologia firmy Microsoft, aby wyszukać terminologię specyficzną dla produktu lub pobrać kolekcję terminologii firmy Microsoft w swoim języku.
• Więcej informacji na temat lokalizacji można znaleźć w sekcji dotyczącej komunikacji globalnej w przewodniku redakcyjno-stylistycznym firmy Microsoft.

Uwaga

Większość zlokalizowanej dokumentacji nie oferuje możliwości edytowania ani przekazywania opinii za pośrednictwem usługi GitHub. Aby przekazać opinię na temat zlokalizowanej zawartości, użyj https://aka.ms/provide-feedback formularza.