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

[Kirill Maslinsky]

Добрый день!

Прошу прощения за задержку с ответом, не хотел отвечать наспех.

> > Если сразу править именно исходный
> > вариант, предоставленный автором, то всё равно потом придётся дублировать
> > изменения в DocBook. Но, конечно, и автору нет смысла пренебрегать чаще
> > полезной, чем вредной литературной и прочей правкой. 
> 
> Тут есть два момента. Во-1-ых, вы сами сказали, как возвращать редактуру в исходный
> текст - неясно. Собственно одна из проблем, которые у меня встали при работе с Docbook в прошлый
> раз - это то, что текст в докбуке даже после моих небольших усилий по его разметке, перестал
> быть читабельным. 

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

Вариант 1: автор предоставляет текст, редактор что-то правит, автор принимает или не принимает правку, и так пока они не договорятся, _после этого_ текст
размечается в DocBook. Получается длинный редакторский цикл (минус) и хороший текст (плюс). Если потом автор предоставил новую версию текста -- 
хо-хо! -- задачка для редактора отследить все изменения (хорошо, если автор пишет в plain text, а если в OOo!), внести необходимую правку в эти изменения,
договориться с автором и _внести_ нужные изменения в DocBook. Мучительно 
хочется упростить кропотливую работу по отслеживанию и внесению изменений. 
Проблемы бы не было, если бы процесс преобразования в DocBook был
автоматическим, но, но...

Вариант 2: автор предоставляет текст, редактор _сразу_ размечает его в DocBook, 
после чего правит авторский и DocBook вариант параллельно (что ужасно), либо 
автоматически вносит все изменения из докбука в авторский или наоборот (что возможно?). Получается, что сразу есть непроверенного качества текст в докбуке, причём качество текста улучшается по мере прохождения редакторского цикла, и он в любом срезе технически доступен для публикации (плюс), но как избежать двойной ручной работы редактора? (минус, и пребольшой). Если автор потом 
предоставит новую версию текста, см. вариант 1.

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

Дабы вести разговор о правке конкретно, я перечёл документацию из rpm-build-python, и посмотрел, что бы мне хотелось в ней изменить при публикации в 
книжке alt-docs-devel. 

Там есть опечатки, есть недостающие знаки препинания, есть пара грамматических 
несогласованностей. Наверное, Вы не станете возражать, что всё это полезно 
исправить перед публикацией, да и вообще полезно исправить. Есть слово "чбы", 
которое я бы, грешным делом, заменил на "чтобы", хоть оно и яркий маркер 
авторского стиля, но всё же не единственный, и, я надеюсь, не самый дорогой
автору ;)

Что касается жаргона, то ничего криминально-жаргонного я в Ваших текстах 
не встретил, и почти все термины у Вас, кстати, переведены. Кроме того,
некоторая специальность текста не противоречит идее книжки: она же адресована
разработчикам или будущим разработчикам, т. е. достаточно хорошо владеющим
жаргоном людям, иначе они бы даже не взялись становиться разработчиками.
Вот если бы речь шла о документации для пользователя, то никакая жаргонность
была бы неуместна, просто потому что текст в этом случае становится совершенно
непонятным пользователю, хоть и кажется совершенно ясным специалисту. 

Единственный вопрос вызвал термин "кляуза" -- я так и не понял, это "clause"? Если так, то русская 
транслитерация его была бы "клауза", а то получается странная путаница 
паронимов. С другой стороны, я эту кляузу встречал ещё где-то, и если так уже прочно принято, то лучше, конечно, не ломать традицию.

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

Приведу одно предложение из Вашего текста, которое мне бы хотелось перестроить:

> Определение зависимостей основано на нахождении в модулях конструкций с
> оператором import и использование его параметров для построения
> зависимостей.

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

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

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

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

Вообще таким общедоступным местом должен стать alt-docs-devel. На него 
предлагаю и ориентироваться. Димины тексты там есть, если появится 
необходимость сослаться и на другие полиси, имеющие отношение к сборке пакетов,
если смысл заняться и их включением в alt-docs-devel (по крайней мере толкнуть
на эту тему авторов и меня).

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

Но тогда проблема и с замечанием, что текст мог устареть -- пользователь 
точно так же может его проигнорировать и недоумевать потом. Лучше уж
предоставить побольше информации заинтересованным лицам.

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

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

Ну так это бы нужно и написать в начале полиси, логично? Я не нашёл, м. б. 
пропустил?

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project