Документация?
Памятка выпускающего дистрибутив
В каком состоянии документация к моему (почти готовому) дистрибутиву?
Для начала, ее нет.
Чтобы она была сделана своевременно, нужно как можно раньше (в идеале -- как только принято решение о выпуске):
Найти виноватого: определить, кто будет ответственным за выпуск документации дистрибутива. Для начала или на крайний случай им может быть сам выпускающий дистрибутив.
Сообщить виноватому о том, что его ждет. (К сожалению, этим пунктом часто пренебрегают. А зря!)
Сформулировать проектное задание по документации -- в противном случае документация может оказаться не такой, какой вы ее ожидали/хотели увидеть. См. следующий раздел.
Что будет в документации?
Прежде чем задавать выпускающему документацию этот вопрос, необходимо ввести его в курс того, что такое <дистрибутив> и поставить задачу. При этом нужно сообщить ему, как минимум, следующую информацию:
Что такое <дистрибутив>?
- целевая аудитория дистрибутива, разные категории пользователей в рамках этой аудитории, предполагаемый уровень их подготовки
- класс прикладных задач пользователей, решаемых средствами дистрибутива (по возможности подробнее)
- компонентный состав (список пакетов)
Какая документация нужна в <дистрибутиве>?
- В какой форме (электронная+печатная)?
- В каком примерно объеме (в страницах печатной док-ии с указанием формата книги/буклета)?
- Возможно, есть пожелания по характеру изложения, уровню сложности материала, количеству иллюстраций и т.п.?
- Приоритетные темы, которые обязательно должны быть освещены в документации -- список, по возможности с кратким разъяснением/обоснованием по каждой теме.
Как поучаствовать подборе/правке/создании материалов?
Подписаться на список рассылки docs@. Предпочтительно все вопросы по документации обсуждать там.
Подбор: Просмотреть документы, доступные в репозитории свободных документов (Куче), часть из них наверняка сможет войти в документацию к вашему <дистрибутиву>.
Правка: См. совместную работу с документами в git и текущий цикл работы с документами. К сожалению, пока не все здесь описано достаточно полно и доходчиво, поэтому, пожалуйста, не стесняйтесь задавать вопросы в списке рассылки.
Создание: главное, пишите, в любом удобном вам формате -- и присылайте выпускающему документацию и/или в список рассылки. Большим подспорьем будет публикация написанных вами текстов на условиях свободной лицензии в Куче.