[docs] Re: [devel] ALT packaging docs (was: О сборке программ на GTK / GNOME)

[Andrey Orlov]

On Saturday 13 November 2004 02:52, Kirill Maslinsky wrote:
> > 3. Как будут решаться вопросы с литературной правкой? Чгря даже на случае с Zope у меня были некоторые проблемы, а то была все-таки
> > более менее старательно написанная документация, тогда как в случае с полиси литературность я однозначно приношу в жертву оперативности
> > обновления и однозначности текста. 
> 
> Для литературной правки есть отличный момент перехода текста из авторского
> варианта в DocBook. Можно и нужно делать не только разметку текста, но и
> редактуру (так, впрочем, почти всегда и происходит). Серьёзная проблема,
> которой я пока не могу предложить никакого практического решения -- как потом
> обратно вносить редактуру в авторский текст? Если сразу править именно исходный
> вариант, предоставленный автором, то всё равно потом придётся дублировать
> изменения в DocBook. Но, конечно, и автору нет смысла пренебрегать чаще
> полезной, чем вредной литературной и прочей правкой. 

Тут есть два момента. Во-1-ых, вы сами сказали, как возвращать редактуру в исходный
текст - неясно. Собственно одна из проблем, которые у меня встали при работе с Docbook в прошлый
раз - это то, что текст в докбуке даже после моих небольших усилий по его разметке, перестал
быть читабельным. Когда туда начали добавлятся более-менее серьезные усилия специалистов, я просто
перестал ориентироваться в тексте и его обновление стало очень мучительным (у меня довольно
страннное восприятие текста, я помню сформатированный текст чисто зрительно очень большими кусками,
и за счет этого легко в нем ориентируюсь и быстро позиционируюсь в нужном месте: но текст для этого должен быть
более-менее аккуратно сформатирован, иначк узнаваемость теряется - в постоянном "шуме" ориентироаться
невозможно; цитаты исходного кода с заменами < > на &lt; &gt; уничтожили один 
из основных ориентиров (код я помню лучше, чем пояснения к нему), кроме того, я легко выхватываю из 
текста ключевые слова (там Zope, Python) когда их тоже стали заменять на
&altlinux; в общем, для меня настал крындец). Я долгое время думал, что это моя личная проблема, но
вот на недавнем линуксфесте узнал, что проблема достаточно общая.

Сама литературная правка, знаете ли, тоже. С бытующей в рашн-комьюити политикой пафосного отношения к документации -
когда оттуда удаляются все мало-мальски скользкие и личные выражения, сленг и все остальное, после чего из него
начисто пропадает все ощущение автора - я не согласен категорически. И не думаю, что  мне кто-то сможет объяснить,
почему мой текст, составленный в т.ч. и после того, как я ознакомился с неким прототипом (и возможно не одним), составленном
в достаточно игривой манере (на английском языке, правда), должен становится нудным, тухлым и тусклым документом
со сложноподчиненными выражениями на три страницы в его русской интерпретации.  В общем, по-моему тут происходит
явная подмена науки наукообразием. Другая, столь же острая проблема (особенно в отношении Полиси), это перевод 
терминов. Может быть, кому-то после этого текст становится понятным.  Но тем, для кого он писался, и даже тому 
__кем__ он писался текст перестает быть понятен абсолютно. 

Насколько я готов включать результат такой правки в текст - я, честно говоря, не знаю.  Иногда меня удается убедить. 

> > 4. Python-полиси содержит явные и неявные ссылки на другую аналогичную документацию, в частности из пакета rpm/rpm-build. Будет ли
> > эта документация поддерживаться там же (может быть, уже поддерживается)?
> 
> Честно говоря, лучше все неявные ссылки сделать явными. 
> Уверен, что это во всех случаях возможно и в подавляющем большинстве -- 
> полезно.

Для этого их нужно позиционировать. Для этого нужно чбы было общедоступное место,
в котором эта документация гарантировано есть. Иными словами, нужно чбы коллекция 
полиси была замкнутой и мне не нужно было описывать "как поскипать (например) поиск зависимостей
в каталоге /usr/share/doc", зная, что это описано в таком-то месте другой полиси. В текущей ситуации
это боле-менее срабатывает для rpm (-build?) (там где Димина дока про макросы), в остальных случаях
ситуация хуже. Даже от участвующих в текущем треде людей я пару раз получал отсылки к документации,
якобы формализующей то-то и се-то, документация была - а вот ни малейшего упоминания того-то и сего-то
 - не было.

> > 5. Как будет решаться вопрос с версиями, а самое главное - с паралельными ветвями полиси? 
> > Сейчас версия полиси лежит в пакете rpm-build-python 
> > и возможность установки и использования этого пакета примерно совпадает с границами 
> > применимости полиси, это, может быть, не совсем 
> > удобно, зато  управляемо, объяснимо и воспроизводимо.

> А если в начале каждого полиси, опубликованного в alt-docs-devel, поставить обязательную краткую справку:
> к какой версии соответствующего продукта этот  

Как бы еще обязать читателя ее прочитывать? Знаете, я работал над одной книжечкой старательно протестировал
все примеры и выписал там же все номера версий использованноег софта и т.д. т.п. Через два года после издания
посыпались жалобы читателей что книга "ужасна" так как "ни один" пример не работает. Объяснение очень простое:
за два года сменились мажоры подавляющего большинства продуктов. А вспомнил я это как пример отношения
читателей  к таким комментариям. Конечно, я всегда могу отмазаться, показав комментарий - но потребителю от этого
не легче.

> текст относится, какой он имеет статус (пробный, предложение, обязательный
> и общепринятый, устаревающий и т. п.), и также _какие ещё_ версии существуют
> наряду с ним, _где_ и _с каким статусом_). 

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

> При всем alt-docs-devel я готов в начале поставить объяснение его статуса: 
> отражает текущее состояние разработки, поэтому если Вы хотите знать наверняка --
> не полагаётесь на печатную версию или пакет в дистрибутиве, смотрите последнюю 
> версию в Сизифе или на сайте. 

Да, конечно. По крайней мере первое время.

-- 
WthBstRgrds -- Андрей Орлов --  
 --- http: www.neural.ru, mail: cray на neural.ru, jid: cray на altlinux.org ---
----------------------------------------