[docs] ALD Roadmap, альфа-версия

[Fr. Br. George]

Всем привет.

Попробуйте предложить _всем_ перейти на какое-нибудь _одно_ средство
разработки, и послушайте, что они про вас скажут :).

Сколько авторов, столько и удобных для них режимов работы. Постулируя
какой-то один, мы обрекаем N-1 авторов на неудобный режим работы. Таким
образом, остаётся ровно один автор плюс те, кого по тем или иным
причинам удалось уговорить на этот режим работы перейти. Этим кончается
_любая_ попытка вводить single source формат. Этим кончилась попытка
держать всю документацию в DocBook+CVS. Если к Куче относиться как к
средству _работы_ с документом, она окончится тем же. Нет никаких
универсальных способов заставить автора изменить удобный ему метод
разработки. И не надо!

Кто хочет разрабатывает свои документы как хочет. Раньше такого В ALD не
было, был только CVS, теперь есть свобода выбора, а CVS никуда не делся,
им вполне можно пользоваться для совместной разработки какого-либо
документа, так же, как и раньше. Кому неудобно CVS -- есть
sisyphus.wiki, модуль импорта оттуда понемногу пишется, это довльно
просто.

Теперь -- куски Roadmap.

Куча -- _не_ средство совместной разработки.

Это:

1. Категоризированный архив (аггрегатор) документов (планируется
   написание поискового движка или адаптация какого-нибудь имеющегося).
   В отличие от интернета, где эти документы валяются как попало и часто
   умирают вместе с URL-ями, документы в Куче исчезать не собираются (за
   исключением obsolete) и хранятся в унифицированном виде.
2. База для (полу)автоматической сборки пакетов документации в Сизиф.
   Если документ написан в одном из "известных" форматов (на сегодня это
   -- DocBook, m-k и сам HTML, планируется также Wacko), робот
   немедленно попробует собрать из него пакет документации (модуль) в
   HTML. Если в "неизвестном" формате (например, OOo) -- припишет к нему
   index.html с описанием, как и чем просматривать документ, и
   опять-таки соберёт пакет. Если AI барахлит, майнтейнер из ALD
   (_совсем не обязательно_ автор!) подправит spec так, чтобы модуль
   собирался правильно. Это значит, что автор может с большой
   вероятностью увидеть свой текст в свежем Сизифе.

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

   Взаимодействие ведётся посредством майнтейнера. Каков бы ни был
   способ обратной связи с автором, не стоит сваливать его по умолчанию
   на добровольца, взявшегося прочитать документ. Если автор хочет,
   чтобы все подряд редактировали его текст, он просто в поле URL
   docinfo укажет, на какой Wiki идти. Заметьте, что эта информация
   окажется непосредственно в выпуске.

   Если не хочет -- предполагается, что это личные его с майнтейнером
   разборки. Тогда доброволец вешает багу, майнтейнер связывается с
   автором, возможно сам эту багу правит, если автор разрешает доступ к
   своему CVS/Wiki/... только ему.

	
	Чего не хватает.

Первая очередь.
-  Для тех, кто не использует Сизиф, планируется в самое близкое время
   (хорошо бы до конца месяца) выложить (и выкладывать автоматом) все
   выпуски документации на WWW. Поскольку модуль -- это пакет Сизифа и
   информация о пакете в выпуске доступна, автоматически возникает обратная
   связь в виде Bugzilla.altlinux.org. Будет формироваться также и
   "автоматический" выпуск: последовательность всех модулей из Сизифа.

   На первых порах это послужит заменой общей поисковой машине с
   обратной связью (т. н. "Сизиф-на-Куче"), котороый ещё программировать
   надо.

   UPD: оно уже зашевелилось:
   http://heap.altlinux.ru/alt-docs

-  Конвертор из Wacko в HTML уже есть, так что добавление Wacko в список
   "известных" также произойдет в районе конца месяца, если ничто не
   помешает.

-  Будет написан ALD Roadmap по мотивам этого письма и народных
   обсуждений.


Вторая очередь (вопросы)

-  Помещение документа в Кучу.
   Неоднократно в этой рассылке возникали утверждения, что формат, в
   котором документы принимаются в Кучу противоестетсвенен и неудобен.
   Прошу покорнейше описать -- чем. С моей точки зрения упрощать
   процедуру больше некуда (пересказ текста с http://heap.altlinux.ru):
   1. Создание docinfo и License
      Это, действительно, процесс, требующий некоторого времени.
      Допуская, что на принятие решений по заполнению docinfo требуется
      в среднем полминуты на поле, получаем 15 минут. Это совершенно
      необходимая операция -- реферирование -- иначе Куча станет обычной
      кучей каких-то документов, информацию о которых можно получить
      только прочитав их. И только автору читать собственный текст
      необязательно; ergo заполнение docinfo -- доброе дело.

      Без знания условий, на которых распространяется текст,
      распространять этот текст мы не можем :) -- отсюда следует наличие
      файла License. Если вам лень выдумывать какую-либо лицензию,
      пишите "GPL" :).

      Оба этих файла можно хранить в том же CVS / Wiki / darcs /
      файлопомойке / whatever, что и сам документ (вы ведь не
      собираетесь _часто_ изменять, например, автора, стиль изложения и
      пр.?), так что после однократного создания трудозатраты
      заканчиваются.

      Затруднения?

   2. Создание tar-архива.
      Файлы License и docinfo и подкаталог с документацией должны лежать
      на одном уровне -- либо в корне tar-а, либо в подкаталоге. Имя
      архива должно быть уникальным среди всех _ваших_ документов.
      Это достигается одной командой, если в вашем дереве разработки
      файлы так и хранятся, и шестью, если они хранятся не так,
      например, первые пять команд можно пропустить, если у вас уже
      имеются License, docinfo и каталог subdir с деревом документации:
	mkdir tmp/newdoc
	cd tmp/newdoc
	cp $PATH_TO_LICENSE License
	cp $PATH_TO_DOCINFO docinfo
	cp -r $PATH_TO_ALLDOCS_DIR subdir
	tar cjvf /tmp/ThisDocument.tbz License docinfo subdir
      
      Затруднения?

   3. Закладка в Кучу.
      Надо -- однократно -- зарегистрироваться и отослать ssh-ключ (так
      же, как это было и в CVS!). Надо настроить ssh и уметь запускать команду
	rsync -Pva --stats -e ssh имя_файла_документа incoming:/incoming/docs/
	
      Затруднения?

      Можно организовать несколько других входов в Кучу, вот только
      строгая идентификация в них всё равно останется (как была она и в
      CVS) по соображениям безопасности и отслеживания авторства.
      Предложения?

- Обратная связь:
  Нужно ли организовывать ещё какую-то общую обратную связь на уровне
  Кучи и Сизифа-на-Куче? Стоит учитывать, что исходный формат документа
  может быть разным, а стало быть способы этой обратной связи --
  варьироваться от документа к документу. И что читатель Сизифа видит
  HTML, а не исходный формат -- как единственный способ _представить_
  корпус документации сообществу. Можно придумать что-то вроде
  HTML-Diff (скажем, жабаскриптового), когда читатель отмечает место с
  ошибкой, вписывает в формочку исправление и отсылает результат (вместе
  с автоматичевки сгенерированным описанием, в каком именно месте
  ошибка) майнтейнеру... Насколько это актуально?

- Средства совместной разработки:
  Как я понял, wiki.sisyphus и cvs.altlinux не хватает? Что ещё нужно?


Третья очередь (требует программистских ресурсов):
  Сизиф-на-Куче.
  Поисковый движок, основанный на docinfo документов, позволяющий по
  комбинации значений полей и/или подстрок в них (актуально для
  Abstract) находить ALD-документы в Куче, в Сизифе, в выпусках и т. п.
  Более детальная концепция есть, но дело всё равно стоит за отсутствием
  исполнителя.

-- 
			George V Kouryachy (aka Fr. Br. George)
			mailto:george at altlinux_ru