[docs] Re: faq Re: [web] Re: HCL и другие

[Michael Shigorin]

On Wed, Jul 20, 2005 at 12:16:21AM +0400, Denis Smirnov wrote:
> >Или можно сделать "кнопку" "отправить в документацию" и/или
> >"обновить в документации", которая сделает wget и необходимую
> >чистку сама. Тогда нажимать эту кнопку смогут и те (и в первую
> >очередь те), кто документацию на wiki разрабатывает, то есть
> >именно что за ней следит.

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

Здесь есть ещё один нюанс, на самом деле: что является объектом
такого заявления, поскольку вот та же дока по потрохам alterator
физически разбита на несколько частей, а "экспортировать" может
иметь смысл все скопом (после полной проверки/вычитки).

> Дв, именно так. Поэтому я предлагаю решение второго типа --
> мне нужно чёткое ТЗ по формату экспорта, и тогда я смогу его
> реализовать.

А не хочешь покамест просто wiki-форматирование выдавать?
Насколько помню, с год тому его в docs@ начали изобретать.

> >>Пожалуйста, разберитесь с тем, каким образом вы собираетесь
> >>организовывать предпечатную подготовку документов. После
> >>этого я смогу реализовать средства конвертации из wiki в
> >>оптимальные для этого форматы.
> >Тут я исхожу из такого соображения: к оффлайновой документации
> >требования другие (условно -- выше), чем к онлайновой.
> >К печатной -- те же, что к оффлайновой, плюс ещё другие
> >(условно -- ещё выше). Давайте сначала попробуем первый шаг.
> Не могу согласиться. К онлайновой документации требования
> просто _другие_.

Именно.  У онлайновой документации два достоинства: априори
большая возможность быть актуальной и доступность в google.

Соответственно насчёт офлайновой -- есть подозрение, что
тупые и угрюмые статические локальные зеркала ("снимки")
faq.altlinux.ru, lists.altlinux.ru и freesource.info/wiki
на каком DVD (в идеале -- проиндексированные и с искалкой
тут же рядом) -- весьма разумное, хотя и нетрадиционное,
вложение времени.

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

Касательно документации -- наиболее ценным видится именно
сверка, структурирование, техредактирование, литредактирование.
В таком порядке.

> Для меня сделать экспорт один раз и правильно гораздо проще,
> чем делать его в заведомо непригодный к дальнейшей обработке
> html, и иметь в последствии геморрой по полному переписыванию.

Собственно, это уже проходили в docs@ и предшествовавшей ему
вычитке документации к Master 2.0 (в SXW) тремя людьми по почте
-- и DocBook и вообще, и тут появился вовсе неслучайно, при всём
моём специфическом отношении к XML в качестве
человеко-редактируемого формата.

Бишь изобретать ещё раз HTML->SGML->DB/XML действительно
неразумно.

> >И ещё из принципа Late binding -- возникла необходимость,
> >тогда и делай.  Возникла сделать из wiki оффлайновый документ
> >-- прекрасно. Возникнет (когда и если) сделать печатный --
> >будем думать, как сделать.

Вот только хотелось бы иметь инкрементальность трудозатрат на это
(по возможности), а не каждую версию мучать с нуля.

Ср. "The rise of 'Worse is Better'" и "'Worse is Better' is Worse"
:)

> P.S. Извиняюсь если письмо слишком жёсткое, но ситуация
> с документацией в настоящий момент меня очень напрягает,
> а нахаляву я готов работать  во благо _команды_, а не писать
> код в /dev/null.

Лучше сразу расставить точки над "ы", чем потом сокрушаться.

Со своей стороны озабачиваюсь примерно такими же соображениями, 
с той разницей, что меня интересует _и_ "бумажная" сторона
вопроса -- чтоб не изобретать самим.  И ровно исходя из этого 
и бухтел по поводу того, что народ из *компаний*, который
состряпал вполне рабочий фреймворк, разбежался.

PS: есть подозрение, что это уже скорее от web переходит 
в плоскость docs@ -- Денис, ты туда подписан? :)

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