Как принять участие в создании документации

Материал из Mandriva Russian Community Wiki

Прежде всего необходимо:

• подписаться на список рассылки
• получить локальную копию исходников

Принципы работы

Вся система основана на сценариях, которые выполняются всякий раз, когда в репозиторий SVN заносятся изменения.

1. После внесения изменений система проверяет, являются ли изменения корректными и удовлетворены ли все зависимости.
   • Если всё в порядке, изменённое содержимое перемещается в специальный скрытый репозиторий Validated.
   • В противном случае файл помечается как содержащий ошибку, отчёты доступны через интерфейс SvnNav (смотрите ниже).
2. После того, как корректность файлов подтверждена, из них извлекается всевозможная информация: последовательность выполняемых действий, зависимости, и т. д.
3. Затем, система проходит по дереву зависимостей, чтобы проверить, какие публикации (HTML или PDF) были затронуты изменениями, и пересоздаёт эти публикации на neodoc.mandrivalinux.com/publications

Примечание
После внесения изменений вы можете отслеживать процесс, просматривая neodoc.mandrivalinux.com.

Различные инструменты

Вам понадобится редактор DocBook, например:

• emacs + режим nxml
• XXE — свободная персональная редакция для работы со свободной документацией.
• Conglomerate — доступен в Mandriva, но ещё не полностью протестирован.

Чтобы править схемы в формате SVG, вам понадобится программа векторной графики inkscape (входит в дистрибутив).

Интерфейс управления проектом (SvnNav)

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

В каждой папке находится список файлов, которые в ней содержатся, а также дополнительная информация:

• является ли файл корректным файлом DocBook и не имеет ли он неудовлетворённых зависимостей (изображения и т. п.) в колонке Status;
• какая текущая задача (current task) должна быть выполнена для этого модуля.

Щёлкнув по файлу, можно просмотреть страницу подробного состояния, в которой содержится следующая информация:

• Access to validity and dependencies reports in case of problems;
• список переводов этого модуля (если применимо);
• ссылка на исходный файл, если это — перевод;
• ссылка на страницу изменений with respect to previous release (если применимо);
• link to structure diff with original module if applicable;
• полный технологический процесс;
• журнал изменений;
• список зависимостей (файлы XML или изображения, включённые в этот файл);
• список объектов, использующих этот объект (обратные зависимости).

Всё это позволяет организовывать просмотр по папкам или по дереву зависимостей, чтобы, например, проверить все XML-модули, использующиеся в документе.

Технологический процесс

Технологический процесс полагается на очень простую систему, основанную на элементе DocBook — <revhistory>.

Чтобы включить технологический процесс в XML-модуль, просто добавьте специальный элемент revhistory в модуль в верхнюю часть элемента <info>.

Пример:

<?xml version="1.0" encoding="utf-8"?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"xmlns:ns="http://docbook.org/ns/docbook" version="5.0" xml:id="DVD-Booklet" xml:lang="en">
  <info>
    <title>Introducing Mandriva Linux</title>
      <revhistory role="calenco:workflow">
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>2008-03-11</date>
	  <authorinitials>Peter</authorinitials>
	  <revremark>write</revremark>
	</revision>
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>YYYY-MM-DD</date>
	  <authorinitials>Pingusa</authorinitials>
	  <revremark>check</revremark>
	</revision>
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>YYYY-MM-DD</date>
	  <authorinitials>To Be Attributed</authorinitials>
	  <revremark>proofread</revremark>
	</revision>
      </revhistory>
      
......

В технологическом процессе представлено всего 3 шага:

• написание было закончено неким человеком по имени Peter к сроку 2008-03-11;
• проверка технической точности является текущим заданием, которое было выполнено неким Pingusa;
• технический корректор пока что неизвестен.

Чтобы изменить технологический процесс, измените XML-код файла и занесите изменения в SVN:

• измените YYYY-MM-DD на дату, к которой работа была выполнена;
• вставьте имя пользователя учётной записи SVN в тег <authorinitials>, если вы хотите быть ответственным за задачу;
• добавьте или удалите задачи по желанию.