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

Книги

Основная документация OpenERP состоит из набора книг соответственно потребностям бизнеса. Их содержание пересматривается раз в год. Мы работаем вместе с авторами, добровольцами, сотрудниками и переводчиками чтобы написать главы о разных аспектах OpenERP.

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

Построение книги

У нас заключены договоры с многими издателями, чтобы издавать книги в разных странах.

Как только у нас появляется достаточное количество глав, мы можем составить книгу и издать её.

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

Авторские права

Обычно, авторские права составляют 8-10%% от рекомендуемой цены, но зависят от авторов, страны и издателя, который опубликует книгу.Комиссия включена в рекомендуемую цену и не зависит от конечной розничной цены.

Это вознаграждение разделяется между людьми, работавшими над книгой:

• Рецензенты: 10% делится на число рецензентов
• Переводчики: 30% делится на число переводчиков
• Авторы: остальное (60%-90%) делится на число авторов

Например, Geoff и Fabien работали над французской и английской книгами об OpenERP. Эта книга продаётся за 35 EUR с 10% авторского вознаграждения. Рецензентом выступал один человек из Eyrolles. Авторское вознаграждение в этом случае разделиться так:

• Geoff: 1.575 EUR за книгу (= 35 * 0.1 * (0.9 / 2))
• Fabien: 1.575 EUR за книгу
• Reviewer: 0.35 EUR за книгу (= 35 * 0.1 * 0.1)

Если книга будет переведена на Венгерский, с рекомендованной ценой в 30 EUR и авторским вознаграждением в размере 10% (0.1), мы получим:

• Geoff: 1.05 EUR за книгу (=30 * 0.1 * 0.7 / 2)
• Fabien: 1.05 EUR за книгу
• Переводчик на Венгерский: 0.90 EUR за книгу (=30 * 0.1 * 0.30)

Авторское вознаграждение выплачивается каждые 3 месяца, после одного месяца (это может измениться в зависимости от договорённостей с редактором)

Люди

Авторы

Каждый может быть автором и написать целую книгу, одну, или несколько, глав о конкретном аспекте OpenERP. Главы, после этого, рецензируются.

Авторы из Tiny

В Tiny (издатель OpenERP), каждый сотрудник может написать несколько глав на основе основе опыта разработки модуля для конкретного заказчика, по завершении проекта. Поскольку сотрудники компании получают зарплату за написание этих глав в своё рабочее время, авторское вознаграждение вычисляется совершенно по-другому:

• Вычисленное вознаграждение делится пополам для сотрудника: 50%
• Выплачивается, пока сотрудник работает в Tiny

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

Исходные файлы документации могут быть загружены с помощью:

bzr branch lp:openobject-doc

Мы используем Sphinx, генератор документации, чтобы “собрать” документацию. Так что Sphinx должен быть установлен на вашем компьютере и вы должны уметь им пользоваться.

Вы можете установить его с помощью утилиты easy_install. Например, в Ubuntu:

sudo easy_install sphinx

Sphinx — это надстройка над проектом reStructuredText , позволяющим писать документы в виде текстовых файлов и затем генерировать HTML, PDF или файлы других форматов. Хорошим введением в reStructuredText будет страница Quick reStructuredText. reStructuredText определяет поведение и форматирование отдельной страницы. Sphinx позволяет вам организовать некоторое число страниц в большой документ с Содержанием и внутренними ссылками.

Сборка документации в форматы HTML или PDF имеет несколько зависимостей, в основном для системы LaTeX (дополнительные пакеты и шрифты). В Ubuntu вы можете установить требуемые пакеты следующей командой::

# Установить дополнения LaTeX
sudo apt-get install texlive-latex-extra texlive-fonts-recommended
# Установить ImageMagick для преобразования изображений
sudo apt-get install imagemagick

сборка HTML-документации:

make clean
make html

сборка документации в PDF:

make clean
make latex
cd build/latex
make all-pdf

сборка книги:

Например, вы хотите собрать книгу OpenERP для розничного и промышленного управления:

cd books/book_mrp
make clean
make latex
cd build/latex
make all-pdf

Ссылки на комментарии в исходном коде

Некоторые страницы ссылаются на классы в исходных кодах проекта. Например, developer/2_5_Objects_Fields_Methods/methods.rst. Вы можете добавлять ссылки на документацию исходных кодов используя Sphinx autodoc extension. Он импортирует классы и методы вместе с их документацией. Если вы не скажете Sphinx где находится исходный код проекта, тогда импорт завершится с ошибкой Если вы хотите, чтобы импорт работал, проделайте следующее:

1. Похоже, вам потребуется как минимум версия Sphinx 1.0. Если ваша версия не обновлялась автоматически, взгляните на инструкцию к утилите easy_install выше в тексте. Чтобы узнать, какая версия установлена, выполните:

   sphinx-build --help
   

2. Вам понадобится копия исходных кодов сервера OpenERP. Наш сайт собирает документацию на основе trunk-версии

3. Вам нужно будет подправить server/bin/tools/config.py, закомментировав вызов config.parse_config() в последней строке. Мы надеемся вскоре от этого избавиться, но пока что вам понадобится вторая копия исходных кодов сервера для сборки документации или вам придётся добавлять и убирать этот вызов каждый раз при работе с документами.

4. Вам понадобится добавить путь server/bin в переменную окружения PYTHONPATH. Простейший способ это сделать — запускать make таким образом:

   PYTHONPATH=/path/to/server/bin make html

ЧаВо

Сколько экземпляров книги мы планируем продать?

Первая книга на французском, которую мы написали, продавалась по 500 экземпляров в месяц. Это неплохо, так как это была первая написанная об OpenERP книга, но мы можем ожидать лучших результатов для английской версии. Возможно, от 250 до 1500 экземпляров в месяц.