[docs] workflow

[Kirill Maslinsky]

Добрый день!

>   Во время Феста были обсуждения организационных проблем alt-docs.
> На их основе я прикинул возможный вариант распределённого написания
> документации. Комментарии приветствуются.
Мучительно жалею, что не мог быть на фесте, но наконец вошел в строй 
и буду теперь наводнять рассылку. Кто знает, может, это и не менее
эффективный способ обсуждения, чем личные встречи ;)

Комментарии от техписа по текущему состоянию дел.
> Автор пишет текст в удобном для себя формате (примеры: doc, sxw,
> txt, docbook и т.д).
Так оно и происходит.

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

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

> Техпис вносит в систему результат своей работы в неком внутреннем
> формате (например, xml). Система преобразует документы из
> внутреннего формата в нужные форматы (html и pdf).
Есть пожелание относительно "системы": 
хотелось бы, преобразование исходного текста
документации в конечные форматы производилось при сборке "бинарных" пакетов
документации из src.rpm. Так решится и проблема распространения 
исходных текстов документации и (по необходимости) проблема сборочной
среды для документации.

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

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

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

> Автор использует то, что удобно ему. Он размечаеи текст по
> минимуму, используя не более 5-6 тегов (заголовок, параграф,
> выделение и т.д.). Автор придерживается стандартного способа
> разметки. Эти соглашения есть для всех исходных форматов.
Мне кажется очень важным, чтобы автор правильно логически 
размечал свой документ, правильная логическая разметка уже очень
близка структуре "внутреннего формата". Правильно размеченный 
документ позволяет _значительно_ сократить затраты времени на 
его обработку техписом. При любых форматах. Но "правильно
размеченный документ" это ряд весьма конкретных требований, 
которые нужно проговаривать.

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

> Техписовский формат и внтренний формат взаимно однозначны.
Не вижу между ними разницы в принципе. 

> Преобразование между ними происходит без потери информации.
Не вижу необходимости в таком преобразовании, равно как и необходимости 
в отдельном техписовском формате.

> Внесение изменений.
> 
> Только техпис имеет право вносить изменения в систему.
> 
> Если изменения хочет внести автор, то автор обращается к системе и
> система возвращает документ в виде, пригодном для внесения
> изменений. По окончании работы автор передаёт результат техпису.
> Техпис переносит изменения в систему.
Согласен, по крайней мере на данном этапе организации проекта.

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

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project