Какая есть документация¶

Два вида документации (с подразделением)

• внутренняя
  • методологическая - о методике работы, рабочих процессах и пр.
  • документирование кода и программной архитектуры
• внешняя = пользовательская документация
  • методологическая - как сделать то, что нужно. Получить желаемый результат.
    Это то, что обычно нужно пользователю.
  • обзорная/описательная - то, что у нас, в основном, сейчас есть по Д2. "В верхней части окна меню, а в нижней кнопки. Кнопка А - открывает окно, кнопка Б запускает фигню, кнопка С включает режим сторожа"

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

Документацию кода мне кажется правильным оставить в коде и не трогать для этого писателя.

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

Что мы хотим получить¶

Мне кажется, что важнее формирование внешней документации. Хорошая документация

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

Как это получить¶

• Писатель должен быть в контексте задач и знать много.
• Значит, берем его надолго
• Его надо учить
• Он должен уметь
  • внятно излагать информацию, полученную,скорее всего, в не очень внятном виде
  • достаточно быстро писать
  • уметь структурировать информацию - разбивка материала на части очень важна.

В каком виде предоставлять¶

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

Как писать¶

Удобно для нас.
Технически удобно для автоматизации и публикации.

Хотелки¶

• Контроль истории, просмотр разницы, возможность отката.
• "Слой" из прошлого. Если я пошел смотреть документацию в прошлое, то все страницы я вижу как в прошлом. Это важно для естественного получения документация от разных поколений.
• Удобный редактор. Лучше WYSIWYG
• Хранение в тексте, лучше а-ля вики, так удобнее читать и интегрировать.