[docs] ВНИМАНИЕ: отчёт и насущные проблемы
Kirill Maslinsky
kirill на altlinux.ru
Вт Янв 11 15:16:56 MSK 2005
Добрый день!
Прежде чем предлагать полиси, хотелось бы описать текущее состояние дел
в проекте DOCS и его насущные потребности.
Это письмо -- нечто вроде моего отчёта о том, как
происходила работа в прошедшем году. Пожалуйста, прочитайте это
письмо до конца, потому что именно текущее положение дел должно быть
исходной точкой для всех дальнейших обсуждений полиси. В конце --
некоторые конкретные предложения, как исправлять положение дел.
Я не буду описывать, _почему_ делаю так или иначе, это слишком
увеличит текст. Впоследствии могу дать обяснение по любому пункту
заинтересованным лицам и надеюсь услышать конкретные предложения по
исправлению имеющихся несуразиц.
Объём ручной работы
===================
При существующей технологии и инструментарии, подготовка выпусков
документации в электронной и печатной форме требует весьма значительного
объёма ручной работы. Почти вся эта работа может выполняться
автоматически при наличии соответствующих инструментов, а часть можно
было бы не выполнять вообще, ибо она вызвана не собственно задачами
подготовки документации, а спецификой используемых инструментов или
отсутствием оговорённых правил оформления документов.
При подготовке исходных текстов (docbook) к релизу:
---------------------------------------------------
Помимо того, чтобы документ был валидным с точки зрения xmllint,
он должен удовлетворять ещё некоторым требованиям, чтобы годиться
в качестве части общего массива документации и прототипа для будущего
макета. Чтобы его привести в соответствие, нужно:
- Исправить пропущенную и неверную с логической точки зрения разметку.
Несколько примеров.
* Имена файлов и прочие нетекстовые "цитаты из системы" должны быть
_обязательно_ оформлены специальными тегами. Резон в том, что для
них следует применять специальные правила переноса, иначе они все
вылезут на поля. Автомат не может определить сам, где началась
цитата из системы.
* Очень часто требуется привести пример, который пользователь должен
заменить на подходящую строку, например, login name. Чтобы выразить
эту идею чистым текстов, придумана масса способов: <login>,
your_login, _login_, LOGIN. В docbook есть для этого специальный тег,
<replaceable>, которым далеко не все пользуются в соответствующих случаях.
* Все элементы документа, на которые есть (или могут быть) ссылки (в основном
это -- разделы), должны иметь корректный, уникальный в рамках документации
и понятный человеку ID, чтобы потом можно было делать понятные гиперссылки
на другие разделы документации.
* И многое другое.
- Исправить структуру документа, чтобы он вписывался в общий массив
документации. Например, в составе книжки под FDL очень странно смотрится
раздел, в начале которого указано, что его можно распространять под FDL.
Abstract среди документов без Abstract смотрится не менее странно.
Примеры здесь можно множить, но суть, надеюсь, понятна: валидный документ --
это ещё не обязательно готовый документ.
При подготовке макетов печатной документации:
---------------------------------------------
Имеющиеся инструменты авоматической сборки pdf или ps из исходных
текстов документации дают результат, который не годится в качестве
макета по многим причинам. Поэтому используется db2latex, чтобы
получить компилируемый latex'ом текст. Чтобы из этого текста получить
такой, который годится в макеты, каждый раз приходится выполнять
следующие операции:
- Замена преамбулы latex-файла, куда db2latex пишет собственные стилевые
команды в большом количестве и беспорядке, на осмысленную преамбулу.
- Замена некоторых символов (не заэкранированных, редко, но бывает) и
выражений, например, тире с --- на "---.
- Удаление лишних пустых строк, возникших при конвертации, которые в ряде
случаев порождают лишние вертикальные пробелы в макете.
- Удаление лишних команд, вставленных db2latex'ом, которые могут порождать
лишние пробелы и другие проблемы в макете и не делают ничего полезного.
- Удаление погрешностей автоматической обработки. Например, если в гиперссылке
и текст и цель ссылки содержат одно и то же: URL, то возникает URL в тексте,
в сноске к которому -- тот же URL. Если быть честным, это нарушение логики
разметки, несущественное для HTML, но существенное для печати.
- Составление корректного титульного листа со всеми аннотациями и списком
авторов.
- Укорачивание строк в примерах. Количество символов, умещающихся в строку
книжки стандартного формата значительно меньше возможной длины строк
большинства конфигов, которые попадают в примеры. Найти место для разрыва
такой строки автоматически -- невозможно. Более того, желательно даже
разорвав строку примера сохранить его работоспособность (если пользователь
наберёт его as is). В ряде случаев (но не всегда!) этого можно достичь
постановкой символа "\".
Это самая длительная и трудоёмкая операция из перечисленных. При этом
избежать её невозможно вовсе, потому что иначе будут строки, вылезающие
на поля, что недопустимо совсем.
Все перечисленные операции нужно производить при _любом_ изменении исходных
текстов документации. Или приходится вносить изменение параллельно в
исходный текст и latex-файл. Для справки: конвертация текстов одной
книжки db2latex'ом на моей машине требует 10-15 минут.
Вынужденная централизация
=========================
Перед выпуском документации, нужно выполнить следующие задачи:
- собрать тексты (все в разных форматах, как авторы написали);
- добиться того, чтобы каждый текст соответствовал формальным требованиям:
привести каждый текст к "корпоративному" формату, что предполагает
не просто docbook, но и все перечисленные выше операции, для того, чтобы
текст мог стать частью большой документации;
- добиться того, чтобы каждый текст соответствовал содержательным требованиям:
содержал корректную и достаточно новую информацию, был написан грамотным
языком и по возможности понятно.
- собрать в нужном количестве пакеты с электронной документацией, и
добиться, чтобы там всё работало.
- сделать макеты всех необходимых книжек, снабдив их соответствующими
сопровождающими текстами вроде аннотаций, введений и пр., которые
не идут в электронную документацию.
При этом есть некоторые привходящие обстоятельства:
* В docbook.dtd около 400 элементов. Изучение docbook -- большое сложное дело.
* Авторов, пишущих в docbook, фактически нет среди авторов текстов нашей
документации. Есть авторы, которые готовы писать и обновлять тексты, их
тексты нужны, но они обычно не готовы писать и поддерживать их в docbook.
* "Корпоративный" docbook подразумевает ряд требований, которые не входят в
docbook, сформировались в моей голове из практики, и, к сожалению,
пока нигде не описаны.
* Нигде не оговорено, какую именно работу по доведению документа от
исходного текста до пригодного "в модули" документации ALT согласны
брать на себя участники проекта. Фактически, нет распределения
ответственности.
* Время на выпуск релиза очень невелико сравнительно с объёмом работ.
Поэтому получается, что:
- Перед выпуском появляется какое-то количество "сырых текстов";
- Перед выпуском резко (или постепенно) устаревает часть существующих текстов;
- Непонятно, кто за какие тексты отвечает, авторы свои тексты доводить
до конечного состояния не будут. Согласование в рассылке, кто что и
когда будет делать потребует весьма много времени (рабочего времени
выпускающего, в частности). И даже если дождаться такой правки,
при этом ещё останется огромная ручная работа, которую всё равно
делает один человек. Он не успеет её сделать, если получит
правку в последний день.
Таким образом получилось, что всю работу по выпуску документации -- от
исходного текста до пакетов и макетов -- почти исключительно делал один выпускающий. Качество от этого, естественно, страдает.
Это произошло не потому, что было принято решение
централизовать разработку документации. Это произошло потому, что
не было договорённости, какие части этой работы можно поделить между
участниками проекта и, более того, не было способа (технически) передать
части этой работы другим, сохранив при этом целостность и согласованность
проекта.
Насущные потребности
====================
* В репозитории CVS хранятся только тексты в формате docbook.
* Есть люди, которые пишут, поддерживают или просто находят тексты, нужные в документации. Эти люди не готовы размечать текст в docbook.
=> Нужно хранилище исходных текстов в тех форматах, которые удобны
их авторам, которое будет частью docs. Из этого хранилища любой
волонтёр сможет выбрать текст и сделать его пригодным для включения
в общий пакет документации ALT.
Такое хранилище -- это просто "куча" файлов, которая функционирует по
принципу incoming, в идеале сопровождается способом навигации и поиска
для публики и участников проекта.
* Есть тексты, сведения в которых имеют обыкновение устаревать. Их актуальность
нужно проверять перед выпуском. Есть и другие содержательные требования к
части документации ALT, их можно и нужно сформулировать.
* Такую содержательную правку текста может делать только человек,
разбирающийся в предмете. Универсального человека, разбирающегося
во всех предметах, нет.
* Есть и формальные требования к тексту, начиная с формата docbook, но не
заканичвая им.
=> У каждого текста должен быть ответственный сопровождающий (аналог
мантейнера), отвечающий за соответствие текста формальным и содержательным
требованиям.
=> Нужно организовать редакторский цикл для содержательной правки текстов
на уровне Автор текста -- Ответственный за включение текста в документацию
ALT. Этот редакторский цикл должен быть по возможности публичным, чтобы
свои замечания по содержанию могли оставить максимальное количество
заинтересованных и компетентных людей.
Модули
======
Всё вышеизложенное неминуемо подводит к понятию _модуля_ документации
ALT. Модуль -- это документ
- который взят из "кучи" исходных текстов;
- у которого есть ответственный сопровождающий;
- который удовлетворяет формальным и содержательным требованиям, т. е. его
можно без дополнительной обработки включать в состав документации;
К сожалению, принятый в DOCS формат docbook очень существенно ограничивает
круг потенциальных мантейнеров. Напомню, в нём около 400 тегов.
Мантейнер документа -- это специалист в соответсвующей области,
поэтому ему нужен такой документ. Но он вовсе не специалист в docbook,
и, в сущности, не обязательно должен им становиться, чтобы довести
текст до нужной адекватности и обеспечить необходимую _логическую_ разметку.
=> Нужен такой формат разметки, в котором будет различаться ровно
столько сущностей, сколько нужно, чтобы получились адекватные макеты
и гипертекстовые документы. Этот формат может быть любым, единственный
критерий: он должен быть очень небольшим, поддаваться изучению за
15 минут. Как показывает практика, 7--12 тегов будет достаточно для
разметки документации ALT.
Сам формат может быть любым, например, подмножество docbook. Это
вопрос для обсуждения. В следующем письме я попробую сформулировать
требования, которым должен удовлетворять формат, чтобы из размеченных
в нём документов могла получиться и гипертекстовая, и печатная
документация.
Спасибо всем, кто дочитал до конца! Продолжение следует, следите за
рассылкой, и, пожалуйста, высказывайте свои мнения и предложения.
--
Kirill Maslinsky
ALT Linux Team * Documentation Project
Подробная информация о списке рассылки docs