Если вам было поручено написать документ, который должен инструктировать кого-то другого, как что-то сделать, то сегодняшний способ более или менее выбрасывает старые окна в окно.
1. Большие Бомбастические Заголовки
Вы заметите, что заголовки в PCMech, такие как заголовок прямо над этим предложением, огромны. Это потому, что их легче увидеть, прочитать и узнать, где вы находитесь в документе.
2. Меньше слов
Неправильный способ:
Следующая документация объясняет, как использовать и управлять Fanny Whacker 2000.
Правильно:
Инструкция по использованию Fanny Whacker 2000
Всегда помните эту фразу при написании документации: ДОБРАТЬСЯ ДО ТОЧКИ БЫСТРОГО КАК МОЖНО
3. Пропустить бесполезные ссылки
Если ссылка не имеет ничего общего с основной инструкцией того, что вы пытаетесь описать, например:
Для получения дополнительной информации о Fanny Whacker 2000's Turnip Twaddler см. Документ FU, подраздел ID10T.
… не делай этого.
4. Свидание Всегда.
Дата написания документации должна быть в нижней части каждой страницы. Если это электронный документ, дата отображается дважды. Один раз в начале, один раз в конце.
Вы можете написать это как «Последняя редакция (введите дату здесь)».
5. Предупреждения всегда должны быть опубликованы до точки невозврата
Если в вашей документации есть что-то, что может потенциально повредить / уничтожить / уничтожить что-либо при неправильном выполнении, эта информация должна быть размещена непосредственно после указанной инструкции, находиться на виду (имеется в виду на той же странице) и акцентирована.
Пример:
Шаг 5. Чистка Fanny Whacker 2000
Лопасти FW2000 следует аккуратно чистить с помощью неабразивной мягкой ткани.
ПРЕДУПРЕЖДЕНИЕ. Используйте только не содержащий аммиака растворитель, чтобы предотвратить взрыв FW2000 и привести к вашей преждевременной смерти.
В заключение отметим, что хорошая документация не должна быть сверхописательной в отношении каждой мыслимой вещи. Прочитайте свою документацию и спросите себя, правильно ли она дает инструкции? Если ответ «да», то следующий вопрос: быстро ли он дает инструкции? Если да, документация хорошая.
