2022-10-13 Зачем нужны инструкции когда есть документы производителя

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

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

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

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

Часто выполнить одну задачу можно несколькими способами и совершенно незачем в инструкции администратора указывать “все 14 способов создать новую папку”, достаточно одного - самого удобного.

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

В чем преимущества для заказчика проектной документации?

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

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