Документация?

Памятка выпускающего дистрибутив

В каком состоянии документация к моему (почти готовому) дистрибутиву?

Для начала, ее нет.

Чтобы она была сделана своевременно, нужно как можно раньше (в идеале -- как только принято решение о выпуске):

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

2. Сообщить виноватому о том, что его ждет. (К сожалению, этим пунктом часто пренебрегают. А зря!)

3. Сформулировать проектное задание по документации -- в противном случае документация может оказаться не такой, какой вы ее ожидали/хотели увидеть. См. следующий раздел.

Что будет в документации?

Прежде чем задавать выпускающему документацию этот вопрос, необходимо ввести его в курс того, что такое <дистрибутив> и поставить задачу. При этом нужно сообщить ему, как минимум, следующую информацию:

1. Что такое <дистрибутив>?

   • целевая аудитория дистрибутива, разные категории пользователей в рамках этой аудитории, предполагаемый уровень их подготовки
   • класс прикладных задач пользователей, решаемых средствами дистрибутива (по возможности подробнее)
   • компонентный состав (список пакетов)

2. Какая документация нужна в <дистрибутиве>?

   • В какой форме (электронная+печатная)?
   • В каком примерно объеме (в страницах печатной док-ии с указанием формата книги/буклета)?
   • Возможно, есть пожелания по характеру изложения, уровню сложности материала, количеству иллюстраций и т.п.?
   • Приоритетные темы, которые обязательно должны быть освещены в документации -- список, по возможности с кратким разъяснением/обоснованием по каждой теме.

Как поучаствовать подборе/правке/создании материалов?

1. Подписаться на список рассылки docs@. Предпочтительно все вопросы по документации обсуждать там.

2. Подбор: Просмотреть документы, доступные в репозитории свободных документов (Куче), часть из них наверняка сможет войти в документацию к вашему <дистрибутиву>.

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

4. Создание: главное, пишите, в любом удобном вам формате -- и присылайте выпускающему документацию и/или в список рассылки. Большим подспорьем будет публикация написанных вами текстов на условиях свободной лицензии в Куче.