[docs] о проектах (was: M24 docs impressions)

[Michael Shigorin]

On Wed, Dec 08, 2004 at 06:46:13PM +0300, Kirill Maslinsky wrote:
> Я пытаюсь найти именно удобный для всех способ поддержания
> документов в актуальном состоянии. Или по крайней мере
> мониторинга этого состояния. 

Это понятно.

> Действительно, у каждого текста может быть человек, который по
> этому тексту эксперт: способен оценить его качество,
> соответствие действительности и т. п.

А ещё лучше -- группа заинтересованных.

> Речь совсем не идёт о том, чтобы перекладывать ответственность
> на волонтёров.

То было применительно к ALT сказано, а не про docs.

> > > Действительно важная проблема: оценка адекватности текстов.
> > Expires: ?
> Вопрос, как бы это автоматизировать хоть отчасти.

Я вижу только "плохие" критерии -- или время (год после
последней правки, взятый с потолка), или версию программы, к
которой можно привязаться.  Новый minor (x.Y) -- смысл "сверить
часы", новый major (X.y) -- смысл поставить таймер (~месяц) на
obsoleting.

По-хорошему, майнтейнеры пакетов, внося в них ключевые изменения,
должны нотифицировать docs@ или Вас (если сами не подписаны), а
ещё лучше -- bugzilla.

2 ldv: кстати, вот ещё один повод подумать о выделении и
окучивании таких "переломных точек"... кажется, это довольно
интересное явление, чтобы над ним стоило подумать.

> Если есть описание определённого ПО, можно смотреть, не
> сменились ли версии соответствующих пакетов, и, скажем,
> отправлять предупреждение. Впрочем, не все тексты устаревают.

Угу.  Т.е. автоматизируемо это до уровня warning, не более.

> > А не хотите написать "введение в docs" -- документ на манер
> > maintainer's howto?  Буду рад помочь соображениями, если они
> > будут признаны полезными и реализуемыми.
> Теперь определённо хочу. Буду рад любым соображениям на эту тему.

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

> > Ну, всё сложнее, но bugzilla у docs тоже есть. :)
> Хитрость в том, что docs@ нужны две багзиллы: одна для уже
> собранной документации, которая представлена в виде пакетов,
> другая -- для исходных авторских текстов (т. е. всех, которые
> есть в docs@).  Или вторая -- излишество и вообще не нужна?

А там есть оверляпы, которые приобретут двусмысленность в
контексте компонент?

> > А у меня тоже возникло дежавю при прочтении.  Этого не должно
> > быть, как это ни смешно. :)
> Предложите, как переписать.

Постараюсь перечитать более внимательно (пока прочёл от корки до
корки только руководство разработчика, остальные -- продиагоналил
или полистал).  И -- вернуться со структурными соображениями.

Специально никому не раздаю пока :-)

-- 
 ---- WBR, Michael Shigorin <mike на altlinux.ru>
  ------ Linux.Kiev http://www.linux.kiev.ua/