[docs] ALT Docs Team Policy. Part 1.
Kirill Maslinsky
kirill на altlinux.ru
Пт Янв 21 18:27:44 MSK 2005
Добрый день!
Уважаемые коллеги, прошу прочесть новый вариант
начала полиси и включаться в обсуждение (особенно
по технической части).
ChangeLog:
* 21-01-2005 Kirill Maslinsky (kirill at altlinux dot ru) 0.0.2
- Участники проекта
+ уточнены описания ответственности участников ADT
+ добавлена роль "Выпускающий редактор" (editor)
+ добавлен подраздел "Как стать участником проекта"
- Репозиторий исходных текстов
+ начальная версия раздела
* 17-01-2005 Kirill Maslinsky (kirill at altlinux dot ru) 0.0.1
- Начальная версия, разделы 0 и 1: цели и участники проекта
-------------- next part --------------
#Версия документа: 0.0.2
0. Задачи проекта
=================
ALT Linux Docs Team (в дальнейшем ADT) -- открытый
общественный проект, ставящий своей целью создание и
поддержание в актуальном состоянии свободной документации по
программам репозитория Sysiphus и решениям на его основе.
Под решениями понимаются способы применения компонентов Sisyphus
для решения прикладных задач пользователей.
В рамках проекта предполагается решение следующих задач:
* Мониторинг потребностей в свободной документации.
* Улучшение имеющихся и создание новых документов,
поддержание репозитория свободных документов.
* Адаптация имеющихся и создание новых инструментов для
поддержания полного жизненного цикла репозитория документации.
* Публикация репозитория свободной документации в режиме онлайн
на сайте docs.altlinux.ru, а также в виде пакетов в Sisyphus и
немедленное обнародование всех изменений и дополнений в
репозитории.
* Взаимодействие с работающими под свободными лицензиями
техническими писателями и нахождение новых участников
проекта, организация взаимодействия между техническими
писателями и свободными разработчиками.
* Взаимодействие с существующими учебными и методическими
организациями, заинтересованными в наличии свободной
документации.
* Выпуск регулярного периодического издания.
1. Участники проекта
====================
В проекте есть пять ролей: автор, сопровождающий (maintainer), редактор
(reviewer), ответственный редактор (editor) и выпускающий (release manager).
Автор:
Участие в ADT:
Копирует тексты в репозиторий исходных текстов документации(?ссылка)
(``кучу''), взаимодействует (если хочет) с сопровождающим по поводу
своих текстов. Автор должен понимать, что, копируя свой текст в
репозиторий, он даёт согласие его на свободное распространение и
доработку документа и, следовательно, текст получает шансы на
публикацию. Подробнее см. (?ссылка на раздел ``куча'').
Формат текста:
``Любой'' (лучше -- конвертируемый в формат
разработки ADT, ещё лучше -- конвертирумый в обе стороны).
Ответственность:
При копировании текста в репозиторий описать его
в соответствии с требованиями к входящему тексту, приведёнными в
(?ссылка на раздел). Требования эти минимальны, сводятся к тому,
чтобы можно было разобраться, что это за текст, не читая его
целиком.
Кроме того, автор должен отметить, согласен ли он
при появлении новых версий текста копировать их в репозиторий
исходных текстов ADT. Соглашаться необязательно (хотя и желательно).
Если автор отметил, что будет поддерживать текст в актуальном
состоянии, к его обязанностям добавляется своевременное обновление
текста в репозитории ADT. Автор может в любой момент отказаться
от этой обязанности, сняв соответствующую отметку в описании текста.
Строго говоря, роль ``Автора'' не обязательно должен
выполнять автор текста. Если допускают условия распространения
текста, любой может его скопировать в репозиторий ADT, сопроводив
соответствующим описанием.
Сопровождающий (maintainer):
Участие в ADT:
Берёт текст из репозитория исходных текстов (``кучи'') и
превращает его в модуль(?ссылка). Помещает модуль в репозиторий
готовой документации(?ссылка). Взаимодействует со всеми
остальными персонажами.
Формат текста:
Формат разработки ADT.
Ответственность:
Cодержательная (соответствие документа актуальной версии ПО,
исправление ошибок и обновление документа), и формальная
(требования к формату(?ссылка)). Требования к формату обусловлены
в первую очередь тем, что из модуля должны автоматически
собираться конечные форматы (важнее всего HTML -- для публикации
документа в Интернет).
Редактор (reviewer):
Участие в ADT:
Читает опубликованную документацию и сообщает об ошибках
посредством Bugzilla(?ссылка), с её же помощью взаимодействует
с сопровождающим.
Формат текста:
Формат тех публикаций или исходных текстов документации, которые ему
доступны.
Ответственность:
Никакой.
Выпускающий (release manager):
Участие в ADT:
Составляет общий план выпуска документации и собирает её из модулей.
Доводит формат представления до приемлемого уровня.
Взаимодействует со всеми, торопит нерадивых.
Формат текста:
Форматы представления.
Ответственность:
Концептуальная (выпуск должен быть целостным по содержанию),
эстетическая (и красивым).
Ответственный редактор (editor):
Участие в ADT:
Назначается выпускающим для сплошной вычитки и правки материалов
выпуска. Взаимодействует с сопровождающими. Правки, предлагаемые
ответственным редактором, имеют более высокий приоритет, чем правки
обычного редактора (должны вноситься срочно). Имеет право вносить
``пожарные'' правки в пределах опечаток и очевидных погрешностей на
стадии непосредственно перед выпуском без согласования с
сопровождающими соответствующих модулей.
Формат:
Формат разработки ADT.
Ответственность:
В соответствии с тем, какая задача была перед ним поставлена
выпускающим: корректура, литературная правка, содержательная правка --
соответственно, отвечает за отсутствие опечаток, гладкость стиля,
содержательную адекватность документов.
Роли автора и сопроводающего по отношению к тексту может
выполнять один и тот же человек; никому не возбраняется
выступать в роли редактора.
Помимо названных ролей участники ADT занимаются разработкой технической
реализации и автоматизации всего процесса разработки документации.
Техническое обеспечение проекта также порождает ряд вполне определённых ролей,
однако они связаны с конкретными технологиями, поэтому их описания приводятся
не здесь, а в соответствтвующих разделах.
Всем участникам ADT стоит взаимодействовать
с внешним миром и привлекать к проекту новых участников.
Как стать участником проекта
----------------------------
* Чтобы стать автором ADT, достаточно скопировать свои (или даже чужие, но
распространяемые свободно) тексты в репозиторий исходных текстов
ADT. Подробнее см. раздел(?@куча@).
* Чтобы стать сопровождающим ADT, достаточно сделать из имеющегося в
репозитории исходных текстов ADT документа модуль документации и
разместить его в репозитории модулей. Подробнее см. раздел(?ссылка на
раздел про технологию подготовки модулей).
* Чтобы стать редактором ADT, достаточно предложить правку в Bugzilla
на любой из модулей документации. Подробнее см. раздел(?ссылка на раздел про
Bugzilla).
* Чтобы стать выпускающим, достаточно иметь идею, как сделать выпуск на основе
материалов ADT, поддержку сообщества ADT и время на то, чтобы этим заниматься.
* Чтобы стать ответственным редактором, достаточно, чтобы Вас на эту роль
назначил выпускающий.
2. Репозиторий исходных текстов
===============================
Репозиторий исходных текстов нужен затем, чтобы создать обозримое
поле текстов, над которыми работают или собираются работать участники
ADT.
* Такой репозиторий должен быть централизованным, чтобы процесс
разработки мог быть совместным и полностью открытым.
* Репозиторий должен быть доступен для открытого просмотра -- это позволит
участникам и желающим присоединиться к проекту сориентироваться
в имеющихся материалах и свободно получать исходные тексты для
дальнейшей работы. О доступе на чтение репозитория см. (?ссылка)
* Операция записи в репозиторий требует идентификации, поскольку
представивший текст всё-таки несёт некоторую ответственность.
О доступе к репозиторию на запись см. (?раздел)
* Тексты в репозитории должны быть классифицированы: это позволит
легче ориентироваться в том, на какие темы есть материалы. О
классификации текстов см. (?ссылка).
* Тексты в репозитории должны сопровождаться паспортом, содержащим
сведения, необходимые для дальнейшей работы с текстом в рамках ADT.
О формате и содержимом паспорта текста см. (?ссылка).
Человека, копирующего тексты в репозиторий, здесь и далее будем называть
донатором. Человека, отвечающего за предоставление доступа к репозиторию
и обеспечение его нормальной работы, здесь и далее будем называть
Принимающим. Принимающий -- один (или несколько) из участников ADT.
2all: Или назвать принимающего Сторожем?
Доступ на запись в репозиторий
------------------------------
Чтобы получить доступ на запись в репозиторий исходных текстов (стать
донатором), прежде всего нужно написать Принимающему по адресу joindocs at
altlinux.ru о тех текстах, которые Вы хотели бы добавить в репозиторий ADT
(кратко, но убедительно). В этом письме должна присутствовать информация,
необходимая для организации доступа:
* Полное имя или псевдоним участника -- будет использовано для авторизации
при записи в репозиторий и для идентификации его текстов в репозитории.
Не должно совпадать с уже существующими именами.
* Действительный e-mail участника, по которому члены ADT могут с ним свзяаться
по поводу его текстов.
2ldv: SSH/GPG ключи? Или только GPG?
Решение о предоставлении доступа и вся необходимая дальнейшая информация
будут отправлены на адрес, указанный в письме участника.
Получив доступ, можно подготовить пакет с текстом(ами) для копирования
в репозиторий. Этот пакет должен соответствовать требованиям, описанным
в разделе @Формат пакета@.
Формат пакета
-------------
В репозиторий исходных текстов ADT принимаются пакеты с текстами,
оформленные по следующим правилам:
* Все файлы собраны в единый файловый архив в формате .tar.gz. Имя файла может
быть произвольным, но должно быть записано латиницей и желательно, чтобы оно
что-то говорило о содержащемся в файле документе. Нельзя помещать в
репозиторий разные документы под одним и тем же именем.
* В этом файловом архиве содержится (не вложенный ни в какой подкаталог)
файл docinfo, содержащий краткий паспорт документа. Правила оформления
паспорта см. в разделе @Паспорт документа@.
Паспорт документа
-----------------
Паспорт документа находится в файле docinfo в текстовом формате. Формат
паспорта прост: он состот из полей, каждое поле вида "{название_поля}: данные"
и должно занимать одну строку. Все поля должны быть заполнены, пустое поле
считается ошибочным. Список полей:
Title: {название_документа}
{название_документа}
(?без ограничений?)
Language: {язык_документа}
Язык должен быть указан в виде стандартного двухбуквенного кода.
2all: (?Если языком документа является русский, все поля docinfo должны быть
либо в какой-то заранее оговорённой кодировке, либо кодировку
нужно каким-то стандартным образом указывать?)
Authors: {авторы_документа}
Список авторов документа вида {Имя Фамилия}, через запятую.
Имена авторов должны быть записаны по правилам языка документа.
Url: {url_исходного_документа}
URL, по которому можно найти исходный документ.
Format: {формат_документа}
Формат, в котором представлен документ. Если он представлен в
нескольких форматах -- список через запятую.
2all: (?Стандартизовать ли написание названий форматов?)
Abstract: {аннотация}
Краткая (в один абзац) аннотация к документу, из которой должно
быть понятно, о чём он, в чём его специфика и какова ценность.
Section: {классификация_документа}
Классификация документа в соответствии с принципами, описанными
в разделе @Классификация документов@.
Supported: yes/no
Является ли документ поддерживаемым, т. е. будет ли донатор
отвечать на предложения и вопросы по тексту, направленные
участниками ATD.
Updated: yes/no
Является ли документ обновляемым, т. е. будет ли донатор
регулярно отправлять в репозиторий новый пакет по мере появляения
новой версии документа.
Итого 9 полей. На их заполнение уйдёт совсем немного времени.
Чтобы получившийся пакет попал в репозиторий, нужно отправить его в
``точку входа'' -- docs/incoming. См. раздел @Устройство репозитория@.
Классификация документов
------------------------
2all: Это нужно обсуждать. Начало уже положено.
Устройство репозитория
----------------------
Напрямую поместить пакет в репозиторий невозможно, его нужно отправить в
``точку входа'' -- docs/incoming. Это можно сделать командой:
???
Docs/incoming -- это временное пристанище, где хранятся вновь поступившие
пакеты, пока они не будут проверены на соответствие правилам оформления.
Неправильно оформленный пакет (отсутствует или оформлен не по правиламш
паспорт, есть конфликт по имени с уже существующим пакетом и т. п.) не будет
принят к размещению в репозитории, а его отправитель получит письмо с
сообщением об ошибках.
Прошедшие проверку пакеты размещаются в репозитории.
Полное имя документа в репозитории составляется из собственного имени
документа (поле "Name:" docinfo), идентификатора донатора (), даты поступления
документа в репозиторий.
2all: Внутреннее устройство репозитория зависит от Классификации доукментов,
поэтому пока не обсуждается.
За помещением текстов в репозиторий и порядком в репозитории следит
Принимающий.
Доступ на чтение репозитория
----------------------------
2all: Нужно придумать, как это организовать.
Подробная информация о списке рассылки docs