Инструкция по написанию инструкции

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

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

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

Рекомендуется придерживаться следующего шаблона: Шаблон написания инструкции

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

Ниже приведены некоторые полезные рекомендации, которые можно учитывать при составлении инструкций.

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

Справочник по форматированию - Formatting Syntax