Создание документации

Документация в репозитории/дистрибутивах

В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении Linux.

Коллективное обсуждение всех вопросов, касающихся документации, происходит в списке рассылки docs@.

Печатная документация

Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux, в виде брошюр, руководств и т. п. Другой вид печатной документации — отдельные книги, учебники и т. п.

Как правило, печатная документация составляется на основе существующей электронной.

Краткая инструкция по сборке печатной документации.

Электронная документация

Главное в документации — это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в двух видах:

• Текст

Минимальная форма хранения информации.

Текст может писаться с нуля, или заимствоваться из сторонних легальных источников.

Технически может представлять из себя файл(ы) в любом читабельном формате: txt, odt, pdf, html

• rpm-пакет

Это пакет документации опакеченный в соответствии с принятыми правилами упаковки документации

В этом виде документация может быть легко установлена в систему.

Таки образом имеем:

• Текст в любом читабельном формате
• rpm-пакет = текст + spec

Пакет электронной документации

Электронная документация в виде rpm-пакета присутствует в репозиториях/дистрибутивах.

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

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

Пример: docs-simply-linux

Форматы электронной документации

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

Принципиально, оригинальный текст может создаваться в любом формате. Однако существует несколько форматов, для которых поддерживается конвертация в html, что особенно удобно для опакеченной документации.

Документация создаётся разработчиком в одном из поддерживаемых форматов:

• html

Описание формата: http://www.w3.org/html/

• docbook

Описание формата: http://www.docbook.org/specs/

• m-k

Описание формата содержится в документации к пакету ALDConvert

Генерация html происходит в момент создания rpm-пакета.

Процесс опакечивания автоматизирован описан в разделе XXX.

Цикл разработки

• Тексты коллективно создаются и модифицируются в git.altlinux.org

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

• При необходимости создаются пакеты
• Пакеты оказываются в нужном репозитории

Инструменты документатора

git как нельзя лучше подходит для хранения документации.

Publican - утилита для создания документации на базе стандарта DocBook. Утилита предназначена для автоматизации и сокращения сроков развертывания и настройки под конкретный проект DocBook-инфраструктуры, операций экспорта в нужные форматы (в том числе PDF и HTML).

Пример создания пакета документации

• Выбрать один из поддерживаемых форматов
• Создать spec-файл

  При написании spec-файла следует придерживаться общих правил.

Требования к пакетам документации

Именование пакетов

Пакеты следует именовать по следующей схеме: docs-<название_дистрибутива>

Группа для указания в spec-файле: Documentation

Пример:

Name: docs-simply-linux

Group: Documentation

Каталог установки

Файлы пакета документации (html, стили, логотипы и т. п.) устанавливаются в каталог /usr/share/doc/documentation/

Конфликты

Так как пакеты документации устанавливают свои файлы в один и тот же каталог, в системе не должно одновременно присутствовать более одного пакета документации. Для обеспечения этого пакеты должны иметь конфликты на каждый docs-distro пакет, то есть содержать в своём spec-файле:

Cоnflicts: docs-firstdistro, docs-seconddistro, docs-thirddistro

Соглашения при написании документации

• Ссылки на сайты даются с указанием завершающего слэша:

  http://www.altlinux.ru http://www.altlinux.ru/

• Буква ё используется:

  Скрипт для полуавтоматической расстановки букв ё в тексте.

• Обращение вы пишем со строчной:

  Обращаем Ваше ваше внимание …

• Дистрибутивонезависимые модули. Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT.

  В ALT Linux 4.0 Server настройка производится …

• Linux пишем как Linux, но не Линукс. (Исключение: документация для школ — ПСПО)

  Линукс Linux не имеет географического центра разработки.

• Желательно следить за тем, чтобы в теги попадали те слова, которые к эти тегам относятся, например, не нужно писать внутри тегов точку или знак деления:

  который завершается нажатием клавиши<keycap>Enter.</keycap> который завершается нажатием клавиши<keycap>Enter</keycap>.

• В заголовках статей и разделов точки ставить не нужно
• В списках в конце перечислений лучше ставить точку с запятой

Глоссарий терминов

• ALT Linux — дистрибутивы
• ALT Linux — компания (в англоязычных текстах)
• Компания «Альт Линукс», ООО «Альт Линукс», ООО «Альт Линукс Технолоджи»

Руководство_по_написанию_документации

Исторический раздел

Основной источник информации: heap.altlinux.org