[docs] жаргон, редактура и прочие химеры разума

[Alexandre Prokoudine]

Господа,

Я тут внимательно почитал вас через веб-архив и слегка прифигел.

Все ваши аргументы и контраргументы крутятся вокруг одного единственного 
понятия: целостность авторского текста. Сохранение целостности означает 
не полное сохранение авторского текста или правку лишь орфографических, 
грамматических и пунктуационных ошибок. Оно допускает лёгкую правку 
стиля в тех местах, где автор сам же его ломает.

Сохранение целостности авторского текста подразумевает неизбежное 
превращение документации в сборник статей. Если, конечно, вся 
документация не пишется одним и тем же человеком (а в ALT это вряд 
когда-либо произойдёт).

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

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

В настоящее время общемировой тенденцией является создание упрощённого 
варианта естественного языка для написания технической документации. Как 
минимум, создан и благополучно используется Simplified English. Ведётся 
работа над Simplified Russian. Это может сколько угодно претить вашим 
эстетическим воззрениям. Но это здоровая прагматика. Перед тем как 
возражать на этот тезис, прошу внимательно изучить тему.

Окончательный выбор, сохранять ли целостность авторского текста, или же 
адаптировать его, по идее должен определяться политикой компании ALT 
Linux, которая [политика] так или иначе основывается на видении и 
позиционировании себя на рынке разработчиков ПО. Насколько я понимаю, 
эта политика определяется не вами, хотя вы можете умело на неё влиять ;)

Ну а если компания в отношении документации не может принять решение, 
позволю себе порекомендовать обратиться к существующим руководствам по 
стилю написания документации. В качестве примера приведу очень толково 
написанный GNOME Documentation Style Guide.

http://developer.gnome.org/documents/style-guide/frontmatter.html

В целом, я бы порекомендовал выработать схожую политику написания 
документации, основанную на чётком понимании того, кто читатель, что он 
знает и умеет, как ему удобнее воспринимать информацию. Возможный подход 
к выработке политики --- создание use cases. Это будет на порядок 
полезнее безперспективного бодания в списке рассылки.

Далее, я рекомендую продумать стилистические рамки и схематику для 
каждого типа документации. Если это man-страничка, то она должна 
содержать такой-то и такой-то минимум разделов, расположенных в такой-то 
и такой-то последовательности. Если это урок (tutorial, mini howto), то 
он должен строиться по такому-то и такому-то принципу, быть 
иллюстрированным и т.д.

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

Что касается неудовлетворённости правкой, то вывод, к которому после 
печальной истории с документацией к Master 2.4 пришёл лично я --- писать 
документацию по возможности дистронезависимо и юридическими средствами 
лицензии FDL или иной обязать любого редактора и распространителя давать 
ссылку на исходный текст. Это обеспечивает разумный баланс между 
желанием отправить текст в свободное плавание во благо сообщества и 
желанием спокойно спать.

А.П.