Как правильно писать техническую документацию?

Техническая документация полностью завязана на последующее поведение читателя. Читатель затрачивает своё время на чтение вашего творения, потому что он или она имеет намерение сделать что-то после завершения процесса чтения. Этим «что-то» может быть выпечка печенья с кусочками шоколада, остановка ядерного реактора или разработка кластера Hadoop.

Я называю этот процесс — " «7 шагов создания технического документа». Итак: 1. Составляю структуру, как минимум, до второго уровня (если удаётся, то и до третьего); 2. Добавляю иллюстрации в структуру для каждого понятия;

Хорошо сформированная структура является тем остовом, вокруг которого растёт ваш документ. Подготовка технического документа без использования некоторой структуры равносильна попытке ориентироваться в метро Нью-Йорка (469 станций!) без схемы.

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