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

Тон

Пишите с учётом бренда. Mozilla — это выбор пользователя. Мы верим в свободу и гибкость. Мы ценим приватность и безопасность. Мы — некоммерческая организация, управляемая сообществом, с участниками со всего мира, которые разделяют общие ценности.

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

Стиль написания

Пишите для широкой, нетехнической аудитории.

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

Подводя итог, вы должны следовать этим рекомендациям:

1. Будьте кратки. Люди приходят в базу знаний в поисках быстрых решений. Их может не интересовать, как работает инструмент — они просто хотят знать, что им следует сделать, чтобы это исправить. Смело сокращайте слова. Посмотрите, как много вы можете передать меньшим количеством слов. Это как поэзия!
2. Будьте ясны. Избегайте жаргона. Будьте конкретны. Используйте в заголовке и в статье слова, которые использовал бы читатель. Если ваш 13-летний племянник этого не поймёт, напишите так, чтобы он понял. В следующем разделе вы найдёте более подробное руководство.
3. Будьте дружелюбны, веселы и сопереживающи. (Короче говоря: будьте человеком.) Да, пользователи не приходят в службу поддержки в ожидании веселья. Именно это и делает данный подход мощным. Сделайте день пользователя ярче с помощью немного юмора. Но будьте осторожны, чтобы не пожертвовать ясностью, используя забавные метафоры или выражения. Если вы не уверены, как найти баланс, просто напишите прямые инструкции и используйте этот тон во введении или заключении.
4. Расскажите историю. У неё должно быть начало, середина и конец. Но не пишите роман (см. рекомендацию №1).
   • Начало: это даёт читателю некоторый контекст. О чём эта статья и почему она должна меня волновать? Будьте кратки.
   • Середина: Здесь размещаются инструкции. Этот раздел должен отвечать на вопрос «Как мне это сделать?»
   • Конец: Есть ли какие-либо следующие шаги, связанные со статьёй или функцией? Скажите читателю, куда ему или ей следует перейти дальше, если они хотят узнать больше.

Прочтите следующий раздел для получения более подробных рекомендаций.

Стиль написания (подробно)

• Разговорный стиль письма — используйте неформальный, активный стиль, похожий на тот, как вы бы говорили с кем-то лично.
• Юмор и эмоции — использование юмора — это здорово, но иногда его трудно или невозможно локализовать. Эмоции, такие как удивление и «Я этого не знал/Эврика!», могут быть проще для включения в текст.
• Различные стили обучения — как и в школе, люди учатся по-разному. Кроме того, всем полезно видеть один и тот же контент, представленный разными способами.
• Повторение — когда вы объясняете что-то по-другому, с помощью разных средств, вы, очевидно, повторяете это, что является ещё одним хорошим способом помочь людям запомнить важное.
• Изображения и видео — использование изображений и видео наряду с текстом — это не только лучшая альтернатива личной помощи, но и простой способ учёта различных стилей обучения и повторения. Однако слишком большое количество изображений может усложнить локализацию статьи, поэтому старайтесь добавлять изображения только тогда, когда это полезно для понимания шага или концепции. Например, для шага, где нужно нажать кнопку, вы можете написать «Нажмите OK» вместо добавления скриншота диалогового окна с этой кнопкой.
• Действия — особенно в обучающих статьях, хорошо давать людям что-то полезное для выполнения. Одно дело — прочитать инструкции и понять процесс, но часто полезно напомнить и дать людям возможность попробовать всё на практике.

Типы статей

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

• О статье: Эти статьи отвечают на вопросы «Что это…», предоставляя важную информацию, чтобы помочь читателям понять тему.
• Инструкции: Эти статьи сосредоточены на ответах на вопросы «Как…», проводя читателей через шаги, необходимые для достижения определённой цели или выполнения процедуры.
• Устранение неполадок: Эти статьи помогают пользователям выявлять, диагностировать и решать распространённые проблемы, с которыми они могут столкнуться при работе с продуктом, услугой или функцией, отвечая на вопросы «Как…», связанные с решением проблем.
• Часто задаваемые вопросы (FAQ): Эти статьи содержат краткие ответы на часто задаваемые вопросы по одной теме, которые могут не вписываться в другие отдельные статьи базы знаний, предоставляя быстрый справочник по общим вопросам.

Начните с эффективного и описательного заголовка

Хорошо продуманный заголовок — это больше, чем просто ярлык; это первая точка контакта пользователя с вашей статьёй в базе знаний. Хороший заголовок должен не только привлекать внимание читателя, но и служить кратким и информативным предварительным обзором содержания статьи. При создании заголовков для SUMO учитывайте следующее:

• Ясность и описательность: Соответствуйте тому, о чём статья и что ищет пользователь. Будьте кратки, но ориентированы на пользователя.
• Включение ключевых слов: Включайте релевантные ключевые слова для улучшения видимости в поисковых системах и помощи пользователям в поиске вашей статьи.
• Краткость: Делайте заголовки короткими, но при этом предоставляйте достаточную информацию. Короткие заголовки часто более удобны для пользователя. Старайтесь, чтобы заголовки были около 60 символов.
• Ориентация на действие: Используйте глаголы действия, когда это уместно, чтобы указать, что пользователи могут сделать для решения проблемы или достижения цели. Избегайте использования герундиев (слов, оканчивающихся на «ing») в заголовках, чтобы они оставались ориентированными на действие. Избегайте использования заголовков, содержащих «Как…».

Напишите хорошее введение

Наряду с заголовком и оглавлением, введение поможет пользователю определить, находится ли он в нужном месте.

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

Имейте в виду, что хорошее введение обычно может служить хорошим резюме для поиска. Часто вы можете просто скопировать его в поле «Резюме для результатов поиска», и всё готово.

Эффективно организуйте статью

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

Сделайте пошаговые инструкции лёгкими для понимания

Главное, что нужно помнить при написании пошаговых инструкций, — это включать все действия, необходимые для выполнения задачи. Если, например, вам нужно нажать OK после выбора настройки, чтобы перейти к следующему шагу, обязательно включите нажатие «OK» как часть этого шага. Некоторые дополнительные моменты, которые следует учесть:

• Всегда существует несколько способов достижения результата. Мы всегда должны выбирать наиболее удобный для пользователя способ, используя графический пользовательский интерфейс и меню, когда это возможно.
• Используйте полные предложения при описании доступа к пользовательскому интерфейсу.
• Включайте ожидаемые результаты при предоставлении инструкций (например, Нажмите «OK», и окно закроется.).

Читабельность

Текст должен быть читабельным. Для этого вы должны:

• Разделять статью на небольшие логические/семантические блоки с подзаголовками.
• Использовать нумерованные или маркированные списки.
• Писать короткие или относительно короткие предложения.
• Избегать написания больших абзацев.

Нет ограничений по объёму текста. Чем больше материала, тем лучше; однако не следует искусственно его расширять. Предоставляйте только полезную, ценную и необходимую информацию.

Как ссылаться на внешнюю документацию для стороннего программного обеспечения

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

• Быстро устаревающая информация: Обновления стороннего программного обеспечения могут сделать наши инструкции устаревшими, что может запутать или ввести в заблуждение наших пользователей.
• Ресурсоёмкость: Постоянный мониторинг и обновление шагов для нескольких внешних платформ потребует значительных усилий и ресурсов, что может быть нецелесообразно.

Лучшие практики

Чтобы наши пользователи получали самую надёжную и актуальную информацию, не перегружая наши ресурсы, следуйте этим лучшим практикам:

• Ссылайтесь на официальные ресурсы: Всякий раз, когда инструкции касаются стороннего программного обеспечения, найдите официальную документацию или справочные статьи, предоставленные производителем программного обеспечения. Ссылайтесь на эти ресурсы вместо того, чтобы напрямую прописывать шаги в наших статьях.
• Предоставляйте контекст: Кратко объясните, почему вы направляете пользователя на внешнюю страницу (например: «Для получения самых свежих и точных шагов по настройке системных параметров, пожалуйста, обратитесь к официальной странице поддержки [название ПО]»).
• Периодически проверяйте ссылки: Хотя мы стремимся сократить объём обслуживания инструкций для сторонних производителей, периодическая проверка действительности внешних ссылок по-прежнему важна. Если вы заметили, что ссылка устарела или не работает, найдите обновлённую ссылку на официальную документацию и отправьте исправление.
• Отказ от ответственности за внешний контент: При направлении пользователей на внешнюю ссылку дайте понять, что они покинут SUMO и что мы не несём ответственности за содержание внешних сайтов. Достаточно простого отказа от ответственности или примечания (например, «Переход по этой ссылке перенаправит вас на внешний веб-сайт, который не управляется Mozilla.»).

Пример

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

«Для получения самых свежих шагов по настройке системных параметров в macOS, пожалуйста, обратитесь к официальной документации поддержки Apple, посетив это руководство. Обратите внимание, что переход по этой ссылке перенаправит вас на внешний веб-сайт, который не управляется Mozilla.»

Это гарантирует, что вы следуете самым актуальным инструкциям непосредственно из источника.

Технические рекомендации

• Чтобы узнать, как на самом деле создать новую статью, см. Создание новой статьи в Базе знаний.
• Чтобы узнать, как редактировать существующую статью, см. Редактирование статьи в Базе знаний.
• См. О Базе знаний для обзора того, как работает База знаний.
• См. Улучшение Базы знаний для полного списка документации по статьям.

Заголовок

• Длина заголовка: страница результатов поиска Google отображает до 60 символов. Ваш заголовок может быть длиннее, если это необходимо, но убедитесь, что ваши важные ключевые слова включены в первые 60 символов.
• Заглавные буквы: Используйте заглавные буквы как в предложениях. Первое слово в заголовке должно быть с заглавной буквы, а также имена собственные и названия, а не каждое основное слово. Используйте «стиль предложения», а не «стиль заголовка» (то же самое относится к заголовкам разделов). См. раздел Руководство по стилю и правилам оформления ниже для других правил по использованию заглавных букв.
• Не используйте двоеточие в заголовке статьи, так как это мешает созданию вики-ссылки на эту статью (bug 749835). Также убедитесь, что в заголовке статьи нет лишних пробелов, что также помешает работе вики-ссылок.
• Старайтесь разнообразить названия статей. Не используйте одни и те же слова или фразы в каждом заголовке. Например, не всегда начинайте статьи со слова «Как» и избегайте использования названий задач с окончанием «-ing», таких как «Установка домашней страницы».
• Помните, что всё объяснение не должно входить в заголовок. Вы можете использовать резюме, чтобы предоставить пользователю дополнительную информацию о содержании статьи.

Адресная строка (slug)

Когда вы создаёте новую статью и вводите заголовок, SUMO автоматически создаёт адресную строку (часть после kb/ в конце URL статьи). Рецензент может отредактировать заголовок существующей статьи, но адресная строка останется прежней, если не изменить её вручную (это сделано намеренно). Адресная строка имеет ограничение в 50 символов. Пробелы заменяются дефисами. Адресная строка должна соответствовать заголовку, но, учитывая более жёсткое ограничение по длине, не обязательно должна быть такой же.

Исправьте адресную строку

Обязательно проверьте конец автоматически сгенерированной адресной строки. Иногда слово обрывается или она заканчивается дефисом. Пожалуйста, исправляйте такие вещи.

Обновление адресной строки существующей статьи

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

Категории, продукты и темы

В большинстве случаев статья относится либо к категории Инструкции, либо к категории Устранение неполадок. Иногда мы пишем статьи в одной из других категорий, например, статьи «Как внести свой вклад» (как эта). Страница истории статьи покажет категорию.

Статьи также «относятся» как минимум к одному продукту. Они также принадлежат к одной основной «Теме» и, опционально, к «подтеме».

Ключевые слова

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

Напишите хорошее резюме для поиска

Резюме статьи, наряду с заголовком, помогает пользователям судить, ответит ли статья на их вопрос. Мы называем это «доверием пользователя», и оно напрямую влияет на количество переходов по ссылкам. Даже если мы покажем правильную статью вверху списка результатов поиска, пользователю необходимо установить мысленную связь между поисковым запросом и результатами, которые мы отображаем, чтобы он перешёл к статье.

Резюме для статьи-инструкции должно включать темы, освещённые в статье. В статье по устранению неполадок следует попытаться включить симптомы. Кроме того, резюме должно соответствовать следующим рекомендациям:

• Кратко и по существу. Помните объявления в газетах? Пишите в таком же стиле. Поисковые системы могут обрезать всё, что длиннее 140 символов. Если вы используете более длинное резюме, поместите важную информацию в начало. Примечание: Программное обеспечение Базы знаний покажет, что осталось 20 символов, когда резюме достигнет 140 символов, потому что внутренний лимит поиска составляет 160.
• Не используйте вики-разметку.
• Не используйте «Эта статья объясняет» в каждом резюме. По возможности варьируйте. Некоторые другие фразы для рассмотрения:
  • Мы покажем вам
  • Мы объясним
  • Эта страница объясняет
  • В этой статье описывается
  • Узнайте, как

Количество шагов

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

Параллельная структура

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

Например:

1. Найдите Очищать историю при закрытии Firefox. Если этот параметр выбран:
   1. Нажмите на кнопку Settings….
   2. Убедитесь, что История форм и поиска не выбрана.
   3. Нажмите OK.

Указатели направления

Указатели направления — это ссылки или индикаторы, которые направляют пользователей к определённому месту или положению в пользовательском интерфейсе, где им необходимо выполнить определённое действие. Эти указатели помогают пользователям более эффективно перемещаться и взаимодействовать с программным обеспечением, приложениями или веб-сайтами. Обычно они включают фразы, такие как «В правом верхнем углу», «В меню слева» или «Под строкой поиска», которые дают пользователям чёткое представление о том, где найти и выполнить действия.

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

Руководство по стилю и правилам оформления

Как мы уже говорили, при написании следует использовать активный, разговорный стиль. Избегайте фраз вроде «Если закладки пользователя были утеряны» и вместо этого говорите «Если вы потеряли свои закладки». Вот другие распространённые проблемы со стилем и текстом, с которыми вы можете столкнуться при написании статей поддержки: Всегда используйте термины так, как они появляются в интерфейсе Mozilla. Например:

• Слово Plugins пишется без дефиса.
• Слово Add-ons пишется через дефис.
• Home page — это два слова.

Общие компьютерные термины:

• Website — это одно слово. Web page — это два слова.
• Log in и log out — это глаголы. Пример: «Log in to the website». То же самое относится к sign in и sign out. Не используйте «log into» или «sign into».
• Login и logout — это существительные (обычно используются как прилагательные). Пример: «Нажмите кнопку login».
• Используйте email вместо e-mail.
• Множественное число от CD-ROM — CD-ROMs.

Ссылки на mozilla.org не должны содержать указание локали:

• Используйте https://www.mozilla.org/ вместо https://www.mozilla.org/en-US/

При включении ссылок в предложения:

• Избегайте использования «нажмите здесь» или «здесь» в качестве текста ссылки.
  • Правильно: Перейдите в настройки вашего аккаунта, чтобы отменить подписку.
  • Неправильно: Нажмите здесь, чтобы отменить подписку.

Пишите с заглавной буквы следующие элементы:

• Имена собственные и названия, включая названия брендов, продуктов и функций
• Первое слово полного предложения
• Буквы аббревиатур и акронимов, если они обычно не пишутся строчными буквами
• Первое слово в нумерованных или маркированных списках
• Название клавиши на клавиатуре
• Первое слово полного предложения после двоеточия
• Первое слово в заголовке

Mozilla accounts:

• Буква «a» в Mozilla accounts всегда строчная, за исключением элементов навигации, где она используется вместе с другими элементами навигации, написанными с заглавных букв.
• Всегда используйте «sign in» и «sign out».
• В глагольной форме используйте «sign in to your account» (а не «sign into») для грамматической правильности.
• Вы также можете использовать «Sign in with Mozilla».
• «Sign» всегда следует использовать как глагол. Если вы используете его как существительное, используйте «login».
• Используйте «sign up» в качестве призыва к действию для создания нового аккаунта.

Для получения подробной информации о том, как ссылаться на Mozilla accounts в статьях Базы знаний, см. Редакционные рекомендации для аккаунтов Mozilla.

Не используйте «i.e.» и «e.g.». Эти латинские сокращения могут сбивать с толку. Для ясности используйте «другими словами» или «иначе говоря» вместо i.e., когда хотите объяснить что-то по-другому. Используйте «например» или «такие как» вместо e.g., когда хотите привести примеры.

Не используйте серийные запятые в списке элементов. Например, используйте «Расширения, темы и плагины» (без серийной запятой), а не «Расширения, темы, и плагины».

Используйте инициализмы, которые считаются общепонятными. Например:

• HTTP
• USB
• URL

Числа, встречающиеся в версии продукта, кодах ошибок, на клавишах и кнопках, не будут прописываться словами.

Пишите инструкции в активном залоге. Активный залог и настоящее время упрощают инструкции, делая их более лёгкими для понимания и побуждая к немедленному действию. Пример:

«Перезапустите Firefox для обновления», а не «Firefox должен быть перезапущен».

Прописывайте обратные слэши(\) и прямые слэши(/) в путях и при поиске, чтобы избежать путаницы.

Пример: «Некоторые пути к изображениям содержат обратные слэши (\\)».

Сочетания клавиш Пишите с заглавной буквы первую букву сочетания клавиш или комбинации сочетаний: Ctrl + Shift + C или Command + Shift + C.

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

У нас есть специальные визуальные стили для ряда элементов, которые можно получить, добавив соответствующую вики-разметку вокруг элемента. См. Шпаргалку по разметке для наиболее распространённых стилей.

У нас есть специальная вики-разметка — {for} — которая позволяет вам нацеливать информацию на определённые версии Firefox или определённые операционные системы. Например, вы можете отображать один набор инструкций для людей, использующих Windows, и другой для людей, использующих macOS (см. Как использовать For для получения дополнительной информации).