Как написать понятную инструкцию. Опыт инженера

Владимир Юсупов, 2023

Инженеры разучились писать инструкции. Такой вывод сделан автором на основе изучения технической документации в рамках выполнения работ по импортозамещению зарубежного программного обеспечения и разработанных на их основе информационных систем.Автор – инженер с 15-летним опытом работы в сфере информационных технологий – делает попытку улучшить сложившуюся ситуацию.В книге представлены как методологическая составляющая написания понятной инструкции, так и рекомендации по ее оформлению.Книга адресована инженерам, а также студентам инженерных специальностей, и может быть использована в качестве памятки при написании инструкций.

Предисловие

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

Данную небольшую работу можете считать этаким криком души. И далее немного вам поясню, что я имею в виду. Но для начала, как принято в приличном обществе, представлюсь и расскажу немного о себе.

Я — инженер. Когда-то окончил машиностроительный факультет Саратовского государственного технического университета (ныне имени Ю.А. Гагарина). По многим причинам мне не довелось реализоваться по своей специальности, но вот уже почти 15 лет (на момент написания этой книги) я успешно работаю в сфере информационных технологий.

Основными моими задачами на протяжении всего моего профессионального пути являлись разработка хранилищ данных и визуализация данных. При этом практически весь мой опыт связан с конкретным программным обеспечением (ПО) — SAP (в нашем профессиональном сообществе мы используем название — САП). Специалистов, которые внедряют различные информационные системы на базе данного ПО называют SAP-консультантами (произносится, как САП-консультант), коим я также и являюсь. SAP-консультант — это такой «и швец, и жнец, и на дуде игрец», этакий «универсальный солдат», который не только технические настройки и разработки выполняет, но готовит материалы для обучения пользователей, проводит это самое обучение в различных форматах и выполняет много других задач, среди которых и подготовка документации.

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

Теперь вернемся к причинам выбора темы.

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

Если кратко, результаты конечно были удручающими. Инструкции были написаны плохо. Ни понятной структуры документа, ни последовательности шагов и изложения материала и т.д. Хотя, казалось бы, что сложного в написании инструкции. Ни в коем случае не хочу никого обидеть, на мой взгляд, это один из самых простых жанров технической документации. Знай себе, пиши пошаговые действия — делай раз, делай два. Не подводную лодку же построить требуется, в конце концов.

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

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

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

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

Вот лишь несколько простых примеров, которые сходу вспоминаются:

— достаточно часто в рамках одного документа использовались разные термины, обозначающие одни и те же сущности;

— информация, которая логически должна была содержаться в одном разделе хаотично распределялась по всему документу;

— отсутствовала привязка функциональности продукта к конкретным сценариям его использования, то есть в инструкциях просто показывались и описывались какие-то элементы интерфейсов — кнопки, диалоговые окна и т.д.

В конечном счете, мы практически переписывали инструкции заново для своего внутреннего использования в процессе тестирования нового ПО.

Словом, инженеры разучились писать инструкции…

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

Эта книга, как вы видите, действительно небольшая и вам потребуется не больше часа вашего времени, чтобы ее прочитать в первый раз. Затем вы можете обращаться к ней, как шпаргалке или памятке.

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