Про оформление конфигурационных переменных в документации: Про конфигурацию 

  1. Написать Заголовок (название) страницы.
  2. Составить структуру, как минимум, до второго уровня (если удаётся, то и до третьего), если нужно использовать готовый шаблон тут. 
  3. Добавить содержание через кнопку "+" (Вставить прочий контент) > Оглавление.
  4. Добавить иллюстрации в структуру для каждого понятия.
  5. Сделать подписи под иллюстрациями.
  6. Написать текст в соответствии со структурой, соблюдая правило двух предложений и подстраивая структуру под текст.
  7. Редактируем, переделываем.
  8. Отправляем результат специалисту по рассматриваемой теме на рецензирование (специалистом по рассматриваемой теме является лицо, которое в состоянии выявить неточности и неясности в описании).
  9. Снова редактируем работу на основе отзыва рецензента (рецензентов).
  10. Используем разные стили заголовков для автоматического формирования сожержания и для лучшего визуального восприятия текста смотри тут .
  11. Использовать локальные ссылки для внутреннего пространства документации.


1. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд.

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

Поэтому чрезвычайно полезно для вас чётко определиться, какие действия вы ожидаете от читателя после завершения процесса чтения. Изложите ваше намерение с самого начала. Не оставляйте читателя гадать. Ваше заявление может быть простым и очевидным, как, например: «после прочтения данной статьи вы сможете [впишите свой вариант]». Если вы определились с действиями, ожидаемыми от читателя после прочтения, то процесс написания будет для вас легче с самого начала.

2. Пишите в соответствии с правильно сформированной структурой.

Хорошо сформированная структура является тем остовом, вокруг которого растёт ваш документ.

Написание технической документации в соответствии со структурой не означает увеличение объёма работы. Наоборот, нагрузка уменьшается. Работая со структурой, вы знаете, откуда вы выходите и куда собираетесь прийти.

Имеются два правила структурирования, которые я всегда использую:

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

3. Избегайте неоднозначных местоимений.

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

Если читатель при чтении вашего описания вынужден тратить время на выяснение, что же вы пытаетесь ему сообщить, то мало того, что информативный поток будет нарушен, но и читатель, скорее всего, будет запутан. Как только вы привели читателя в замешательство, вы его потеряли. Всё другое в мире, направленное на привлечение внимания вашего читателя, становится для него более притягательным, чем ваше творение. Щелчок по кнопке «Далее» — и ваша работа остаётся непрочитанной.

4. Ясность = иллюстрации + слова.

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

5. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример.

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

6. Не опасайтесь переделок ("Нет предела совершенству" =)

Редко удаётся написать хороший технический текст с первой попытки. Освоение темы, организация подходов и нахождение формы ясного и точного представления идей требует много времени и усилий. Поэтому не стесняйте себя ожиданием, что всё получится прямо с первого раза. Лучше планируйте пройти, как минимум, через три версии вашего творения. Первая версия представляет собой просто некоторый набор слов в печатном виде, давая вам возможность осознать ваши намерения. Вторая версия уже придаёт вашей работе ясность и точность. Затем, когда все факты в тексте проверены, иллюстрации выверены и структура логично выстроена, можно подготовить третью версию, которая будет привлекательной и своеобразной.
Источник:https://habr.com/ru/post/303760/