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

[Denis Smirnov]

Kirill Maslinsky wrote:

>Метафоры -- враги понимания :( Я имел в виду только превращение онлайового
>докумена в полноценный оффлайновый (т. е. без нжуных битых ссылок, 
>оформления сайта и т. п.)
>  
>
Это реализуется элементарно. Я уже более-менее достаточно ориентируюсь в 
коде WackoWiki чтобы делать подообные фильтры.

Кроме того я подумываю таки сделать полуавтоматический экспорт 
документов в wiki-формате + сколько-нибудь приличный wiki->что-либо 
конвертор.

>Про Кучу: это репозиторий документации, который устроен таким образом, 
>что там удобно организовать (полу)автоматическую сборку документации
>в пакеты с Сизифе. Многое в этом направлении уже сделано. Мы заложили 
>туда ещё кое-какую побочную функциональность по поиску документации,
>но не имели в виду делать кучу средством(местом) написания текстов.
>А если что-то внушающее неврное представление об этом написано на 
>heap.altlinux.ru, так не судите строго, а лучше уажите где, я попробую
>исправить.
>  
>
Видимо я неправильно понял цель существования кучи.

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

>Freesource wiki -- очень хорошее место, где появляется и обновляется очень хорошая документация. Хотелось бы, чтобы дорога оттуда в оффлайновую 
>документацию была прямой и очевидной. Давайте начнём строить её каждый 
>со своей стороны, глядишь, всё-таки встретимся посередине. =)
>
>Если так, то с Вашей стороны "кнопка" в том или ином виде, а с моей -- точка
>входа, которая сможет от этой кнопки принимать документы. Все технические
>подробности со стороны docs обсуждаемы и изменяемы.
>  
>
Собственно и с моей стороны всё обсуждаемо. Поэтому делать будем как 
правильно, и для начала таки определимся что именно правильно.

>Вы не возражаете, если я выпущу часть обсуждения про форматы и конвертеры?
>Честное слово, из самых лучших и доброжелательных побуждений.
>  
>
В смысле "выпустите"?

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

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

Мне очень не хочется делать двойную работу.

До тех пор, пока меня не ткнут носом в полиси, где чётко описан весь 
путь формирования печатной документации для дистрибутивов ALT Linux, где 
будут ссылки на документацию по всем использующимся в процессе форматам 
файлов, ПО, скрипты сборки и т.д.  я не могу воспринимать процесс docs@ 
как нечто достаточно серьёзное, чтобы что-то где-то хакать, тем более 
если работа далеко не на пять минут.

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

Удобство ООО АльтЛинукс я буду обеспечивать либо когда будет чёткое 
полиси, по которому будет работать команда. А работу в стиле "сделай 
во-о-он так, ой, не пошло, давай вот так, ой, мы решили опять переделать 
workflow выпуска документации, переделай..." я буду делать только по 
контракту и минимум за 50$/час + за вредность.

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