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

Придумали каркас. Фиксирую его, чтобы сравнить с результатом и не забыть, как до такого дошли.

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

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

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