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

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

Для кого мы пишем статьи?

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

Подбор хорошего заголовка

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

• Для инструкции или статьи: Каким образом я достигну этого результата? (например, как я могу установить домашнюю страницу по умолчанию?)
• Для ссылки на статью: Как называется функция? (например, Что такое вкладки приложения?)
• Для статьи о решении проблемы: Это проблема, которая у меня возникла (например, Firefox стартует слишком медленно)

 Технические приемы написания статьи

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

Вы еще не заснули? Ну что ж, хорошо.

Параграф звучит подобно скучной лекции (ну до того момента, пока не появились единороги). Использование юмора и эмоций (СЮРПРИЗ!) одна из техник для привлечения пользователя. В этом случае информация воспринимается и запоминается гораздо лучше.

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

Статья «Как установить домашнюю страницу» является хорошим примером, который показывает использование всех перечисленных техник.

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

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

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

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

Как организовать статью?

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

Как составить простую пошаговую инструкцию?

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

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

Опять же статья «Как установить домашнюю страницу» наглядно демонстрирует использование приведенных рекомендаций.

Стилистическое оформление (SUMO)

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

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

• «Плагины» пишется слитно, без дефиса.
• «Домашняя страница» - это два слова.

Основные компьютерные термины

• Интернет – пишется с заглавной буквы.
• Вебсайт – это одно слово.
• Используйте email вместо e-mail.
• Множественное число CD-ROM - CD-ROMы.

Ссылки на сайт не должны содержать локали, т.е. используйте http://www.mozilla.org/firefox вместо http://www.mozilla.org/en-US/firefox

Следующие элементы следует писать с большой буквы:

• Имена собственные.
• Первое слово законченного выражения.
• Буквы аббревиатур и акронимов (они, как правило, пишутся в нижнем регистре).
• Первое слово в нумерованных и маркированных списках.
• Имя клавиши на клавиатуре.
• Первое слово в полном выражении следующего за двоеточием.
• Первое слово в заголовке или названии.

Заголовки и Блоки. Wiki группы Mozilla отображается, используя HTML5, который позволяет использовать элемент  <section>. Вы можете использовать элемент <section> для заключения связанного контента в блок. Что это значит для заголовков? Каждая секция может иметь собственный блок контента с начальным заголовком H1.

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

У сообщества Mozilla есть специальные визуальные стили для различных элементов, которые могут использоваться для выделения слов и блоков при написании wiki. Полный перечень здесь.