Краткое руководство по стилю и голосовой связи Microsoft Learn

  • Статья

Это краткое руководство по написанию технического содержимого для публикации в Microsoft Learn. Это руководство поможет вам как при создании новых документов, так и при обновлении существующих.

Рекомендации.

  • Проверяйте правописание и грамматику в своих статьях, даже если для этого нужно скопировать текст в Microsoft Word.
  • Используйте понятный и естественный язык, как будто вы объясняете что-то другому человеку в личной беседе.
  • Используйте простые предложения. Удобочитаемые предложения упрощают использование предоставляемого вами руководства.

Использование принципов стиля Майкрософт

Мы стремимся следовать этим принципам при написании технического содержимого для Microsoft Learn. Возможно, это получается не всегда, но мы стараемся!

  • Сосредоточьтесь на основной задаче. Пользователи, которые обращаются к нашей документации, имеют определенные задачи. Прежде чем создавать содержимое, определитесь с тем, для кого и с какой целью вы пишете. Затем напишите статью так, чтобы помочь целевым пользователям решить поставленные перед ними задачи.
  • Используйте повседневную лексику. Старайтесь использовать естественный язык — слова, понятные для пользователей. Избегайте официальных фраз, но не забывайте о профессионализме. Приводите примеры, которые объясняют новые понятия.
  • Пишите кратко. Избегайте ненужных слов и излишних объяснений. Пишите по делу и не используйте лишних слов и квалификаторов. Пишите короткими предложениями. Держитесь в рамках выбранной темы. Если задача содержит квалификатор, поместите его в начало предложения или абзаца. Кроме того, сведите к минимуму количество примечаний. Используйте снимки экрана, если это поможет сократить текст.
  • Сделайте статью удобной для просмотра. Самое главное должно идти в начале. Разбивайте длинные процедуры на разделы, содержащие более простые группы шагов. (Процедуры, содержащие более 12 шагов, как правило, слишком длинные.) Используйте снимок экрана, если он помогает прояснить процедуру.
  • Демонстрируйте поддержку и участие. Используйте дружелюбный тон и сведите к минимуму количество заявлений об отказе от ответственности. Честно обозначьте темы, которые могут быть неприятны пользователям. Содержание статьи должно быть интересным для пользователей, а не только включать техническое описание предмета.

Вопросы, связанные с локализацией и машинным переводом

Наша техническая документация переводится на несколько языков. Некоторые материалы адаптируются в соответствии с особенностями определенных рынков или регионов. Кроме того, пользователи могут прибегать к услугам машинного перевода в Интернете, чтобы изучать эти статьи. Поэтому при написании статей придерживайтесь следующих правил:

  • Убедитесь, что статья не содержит грамматических, орфографических или пунктуационных ошибок. Это базовое требование. Некоторые редакторы Markdown (например, MarkdownPad 2.0) включают базовые средства проверки орфографии. Но лучше будет скопировать сгенерированный HTML-текст статьи и вставить его в Word. Эта программа оснащена более надежными средствами проверки грамматики и правописания.
  • Делайте предложения как можно более короткими. Сложные предложения с цепочками оборотов усложняют перевод. Разбивайте предложения, избегая при этом избыточности и косноязычия. Статьи должны быть написаны на понятном и естественном языке.
  • Используйте простую и согласованную структуру предложений. Согласованность способствует качественному переводу. Не злоупотребляйте вводными конструкциями и отступлениями. Подлежащее должно быть как можно ближе к началу предложения. Просмотрите опубликованные материалы. Найдите статью, написанную понятным и легко читаемым языком, и используйте ее как образец.
  • Последовательно используйте формулировки и прописные буквы. Снова-таки, важно обеспечить согласованность. Не пишите слово с большой буквы, если это не имя собственное и не начало предложения.
  • Используйте служебные слова. Некоторые слова, которые мы считаем несущественными, так как они подразумеваются из контекста (например, некоторые местоимения, предлоги, союзы и вспомогательные глаголы), важны для машинного перевода. Поэтому не пропускайте эти слова.

Дополнительные рекомендации по стилю

  • Не перемежайте шаги в инструкциях комментариями или отступлениями.
  • Если описание этапа содержит фрагмент кода, добавьте дополнительные сведения об этом шаге в код в виде комментария. Это сокращает объем текста, который пользователи должны прочесть. Кроме того, ключевые сведения копируются в проект кода в качестве напоминания о задачах этого фрагмента, когда пользователям нужно будет вернуться к нему в будущем.
  • Все заголовки нужно писать с большой буквы и без точки в конце.
  • Используйте "войти" или "войти в систему" вместо альтернативных вариантов.
  • Дополнительные рекомендации см. в руководстве по стилю написания документации Майкрософт.

Локализованная документация

  • Если вы участвуете в локализованной документации, обратитесь к ссылкам на глобализацию.
  • Рекомендации по локализации, инструкции по использованию стиля и языка в технической документации, а также сведения о формате данных для определенного региона см. в доступном для скачивания руководстве по стилю на нужном языке.
  • Ознакомьтесь с терминологией Майкрософт, чтобы найти утвержденную терминологию для конкретного продукта или скачать коллекцию терминологии Майкрософт на вашем языке.
  • Дополнительные сведения о локализации см. в разделе "Глобализация" в руководстве по стилю написания документации Майкрософт.

Примечание.

В большинстве локализованных документов не предусмотрена возможность оставлять или изменять отзывы с помощью GitHub. Чтобы предоставить отзыв о локализованном содержимом, используйте https://aka.ms/provide-feedback форму.