Рекомендации по стилю

У вашей документации будут разные читатели, в том числе профессионалы и разработчики, которые хотят познакомиться с .NET или использовать его в своей работе. Вы должны создать качественную документацию, которая будет полезна читателям. В этом вам помогут наши рекомендации. Руководство по стилю содержит следующие рекомендации:

Используйте разговорный язык

Стиль следующего абзаца — разговорный. Тот, который следует за ним, характеризуется более академическим стилем.

Подходящий стиль

Наша документация должна быть написана в разговорном стиле. Читатель должен представлять, что разговаривает с автором, читая наши руководства и объяснения. Фразы должны быть разговорными, но информативными. Читатель будто слушает, как автор что-то ему объясняет.

Неподходящий стиль

Различия между разговорным стилем и стилем, который является более академической обработкой технических статей, явно заметны. Такие статьи содержат полезную информацию, но их авторы придерживались стиля, который отличается от стиля нашей документации. В написании статей для научного журнала используется другой тон и другой стиль. Такие статьи выглядят как сухой отчет о неинтересной теме.

Используйте второе лицо

В следующем абзаце используется второе лицо. А в том, который следует за ним, — третье. Используйте второе лицо.

Подходящий стиль

Пишите статьи так, будто вы обращаетесь непосредственно к читателю. Часто используйте второе лицо (как в этих двух предложениях). Второе лицо — это не только слово "вы". Обращайтесь к читателю. Используйте повелительное наклонение. Расскажите читателю, что ему нужно узнать.

Неподходящий стиль

Автор может использовать третье лицо. При таком подходе автор подбирает местоимение или существительное, обозначающее читателя. Третье лицо хуже воспринимается читателем.

Используйте активный залог

Пишите статьи в активном залоге. То есть в предложении подлежащее выполняет какое-то действие, выраженное глаголом. В пассивном залоге, напротив, действие выполняется над подлежащим. Сравните два примера:

Компилятор преобразовал исходный код в исполняемый файл.

Исходный код был преобразован в исполняемый файл компилятором.

В первом предложении используется активный залог. Во втором — пассивный. (Эти два предложения показывают каждый стиль).

Активный залог легче воспринимать. Пассивный залог труднее для чтения.

Пишите так, чтобы вас могли понять читатели с ограниченным словарным запасом.

Наши статьи предназначены для международной аудитории. Многие читатели не являются носителями английского языка и не владеют им на вашем уровне.

Но все же они технические специалисты. Они разбираются в программировании и знакомы с терминами. Объектно-ориентированное программирование, класс, объект, функция, метод — это знакомые термины. Но не у всех читателей есть диплом по информатике. Например, лучше пояснять такие термины, как идемпотентный:

Метод Close() является идемпотентным, то есть вы можете вызывать его несколько раз, но результат от этого не изменится.

Избегайте использования будущего времени

Не во всех языках будущее время такое же, как в английском. Будущее время может затруднять чтение. Кроме того, при использовании будущего времени возникает вопрос — когда? Допустим, вы говорите: "Вам будет полезно научиться работать с PowerShell". У читателя возникнет очевидный вопрос — когда это будет полезно? Лучше напишите: "Вам полезно научиться работать с PowerShell".

Определение

Если вы вводите новое понятие, сначала дайте определение, а потом объясняйте, в чем его польза. Читатель должен понимать, что это такое, прежде чем узнать о преимуществах.