Перейти к содержанию

Приложение E: Подсказки по написанию хороших статей

Описание Симптомов

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

Не правильно:

  • Симптом: 3Com NIC X1000 имеет следующее сообщение об ошибке: Comu.dll вызвал ошибку на недопустимой странице в модуле Comu.dll.

Правильно:

  • Симптом: Ошибка: «Comu.dll вызвал ошибку на недопустимой странице»
  • Окружение: 3Com X1000, модуль: Comu.dll

Сделайте мысли завершенными:

Правильно:

  • Проблема: Программа вылетает при запуске с ошибкой.
  • Ошибка: «Программа аварийно завершает работу из-за нехватки памяти»

Сообщения об ошибках

  • Ошибка: "<точный текст сообщения об ошибке>"

  • Ошибка: «Не удается запустить программу. Требуемое приложение не распознано»

Если в вашей статье указано несколько симптомов, упорядочьте их в статье следующим образом:

  • Сначала более общий
  • Затем более конкретный
Пример 1:
  • Не удается распечатать файл
  • Ошибка печати файла на сетевой принтер
  • Ошибка: «Неверный макет страницы для этого драйвера принтера. (24301)”
Пример 2:

  • Ошибка: «Недостаточно памяти»

  • Ошибка: «Ошибка записи UDP-пакета 8101»

  • Ошибка: «Нет доступных библиотек документов»

Вещи, которые не нужно писать в статье:

  • «Хочу», «Клиент пытается»

  • «Клиент использует…»

  • «Клиент получает…»
  • «Все работало хорошо, пока я…»

В каком времени грамматически правильно писать статьи

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

  • Неявное утверждение: Не печатается. (Неясно - Что не печатается?)

  • Явное утверждение: Документы не печатаются. (Лучше)

Информация об окружении

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

Примеры хорошей информации об окружающей среде

  • OS X Yosemite версии 10.10.5
  • Майкрософт Офис 2016
  • MacBook Air

Информация об окружении помогает классифицировать проблемы

  1. Не помещайте информацию о нескольких окружениях в одно утверждение.
  2. Изменяйте статьи если требуется дополнить информацию об окружении.

Подумайте о том, что мог сделать пользователь: - Установил обновление программного обеспечения

  • Полностью переустановил ПО

Не правильно: это работало до того, как мы заменили XBTVA на XBTVM. Правильно: произошло обновление с версии 3.2 до 4.0

Решение

  • В Решении должны быть четко перечислены шаги , которые необходимо предпринять для исправления проблемы.
  • Может быть несколько способов решить проблему: формальное исправление или способы обхода ситуации.
  • Если решение имеет ссылки на внешние ресурсы, убедитесь, что они доступны и понятны для данной аудитории.
  • Решение может ссылаться на техническую документацию или на иные внутренние документы компании.
  • Используйте вкладки для форматирования и удобства чтения.
  • Пишите все в виде списка команд в настоящем времени, как будто вы шаг за шагом читаете их клиенту.
  • Не используйте выражения «если-то». Это скорее всего указывает на то, что вам нужны две отдельные статьи с различным окружением.
  • Статья может содержать более одного решения.

Причина

В статье должна быть только одна причина. Если статья имеет более одной причины, вполне вероятно, что это должно быть несколько статей.

Аудитория статьи

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

Статус статьи

  • Черновик (WIP - Work in Progress): Представляет незавершенную работу, никаких исправлений или решений пока не обнаружено.
  • Не проверено (Not Validated) : черновик статьи, которую автор считает завершенной, но не очень уверен в найденном решении. Или автор является Кандидатом KCS и не имеет прав на создание проверенных статей. Неподтвержденные статьи могут быть проверены путем повторного использования.
  • Проверено (Validated): присваивается статье, когда сотрудник уверен решении и правильной структуре статьи.
  • В архиве: Эта статья больше не актуальна.

Источник

  • Основано на опыте: Стандартная статья KCS. Открыта для редактирования и изменения.
  • На основе политик и внутренних документов компании: Создание и изменение статей разрешено только определенным лицам.