Написание инструкций для программ и модулей - на что стоит обращать внимание?

Категория: Технические советы

– Автор: Игорь (Администратор)

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

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

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

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

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

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

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

3. Текст должен быть максимально простым. С точки зрения банальной эрудиции каждый локальный индивидуум... Знакомая фраза? Если в тексте встречается много таких конструкций, то такое творение становится невозможно читать. Каждый сможет вспомнить хоть один такой текст в своей жизни, а так же то, сколько он плевался за все время чтения. Поэтому, при составлении документа, полезно периодически вспоминать такие "шедевры", тогда оценивать свой текст на простоту становится легче.

Если чуть проще и другими словами, то когда вы пишите текст, то фраза "это итак понятно" должна относится только к таким фразам, как "нажмите кнопку", "наведите курсор мышки" и прочее. Все, что по уровню интеллекта находится выше этих фраз, автоматически должно относится к категории "это нужно пояснить".

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

4. Мелочи, мелочи, мелочи. Если у вас ни разу не возникало желание достать топор из кладовки по той причине, что в инструкции не были описаны "очевидные автору" вещи и вы потратили часы впустую, то вам повезло. Важно понимать, что любая неописанная мелочь легко может превратиться в существенную проблему. Например, если вы не напишите, что порядок установки и конфигурации безумно важен (что не следует просто из того, что в инструкции стоят номера перед каждым пунктом, как в обычном списке), то каждый человек, у которого уже что-либо установлено или настроено, мысленно пожелает вам много интересных приключений в жизни.

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

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

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