[docs] [policy] 0.0.3
Kirill Maslinsky
kirill на altlinux.ru
Пн Янв 31 15:15:10 MSK 2005
Всем привет!
Версия 0.0.3 полиси, в которой всё уже определено для того, чтобы
начать заполнять ``Кучу''. Место для ``кучи'' уже создано.
Есть пара вопросов в тексте, обозначенных строкой "2all".
Changelog:
* 31-01-2005 Kirill Maslinsky (kirill at altlinux dot ru) 0.0.3
- Репозиторий исходных текстов
+ выкинуты упоминания донатора и принимающего (нет в участниках проекта)
+ добавлено требование свободной распространяемости документов
+ добавлен к формату пакета обязательный файл License
+ добавлено поле "License" в паспорт исходного текста
+ добавлено описание доступа к incoming/docs
+ добавлена классификация документов
+ s/Bugzilla/BTS/g
+ мелкая правка формулировок
--
Kirill Maslinsky
ALT Linux Documentation Team
-------------- next part --------------
#Версия документа: 0.0.3
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:
Читает опубликованную документацию и сообщает об ошибках
посредством BTS(?ссылка), с её же помощью взаимодействует
с сопровождающим.
Формат текста:
Формат тех публикаций или исходных текстов документации, которые ему
доступны.
Ответственность:
Никакой.
Выпускающий (release manager):
Участие в ADT:
Составляет общий план выпуска документации и собирает её из модулей.
Доводит формат представления до приемлемого уровня.
Взаимодействует со всеми, торопит нерадивых.
Формат текста:
Форматы представления.
Ответственность:
Концептуальная (выпуск должен быть целостным по содержанию),
эстетическая (и красивым).
Ответственный редактор (editor):
Участие в ADT:
Назначается выпускающим для сплошной вычитки и правки материалов
выпуска. Взаимодействует с сопровождающими. Правки, предлагаемые
ответственным редактором, имеют более высокий приоритет, чем правки
обычного редактора (должны вноситься срочно). Имеет право вносить
``пожарные'' правки в пределах опечаток и очевидных погрешностей на
стадии непосредственно перед выпуском без согласования с
сопровождающими соответствующих модулей.
Формат:
Формат разработки ADT.
Ответственность:
В соответствии с тем, какая задача была перед ним поставлена
выпускающим: корректура, литературная правка, содержательная правка --
соответственно, отвечает за отсутствие опечаток, гладкость стиля,
содержательную адекватность документов.
Роли автора и сопроводающего по отношению к тексту может
выполнять один и тот же человек; никому не возбраняется
выступать в роли редактора.
Помимо названных ролей участники ADT занимаются разработкой технической
реализации и автоматизации всего процесса разработки документации.
Техническое обеспечение проекта также порождает ряд вполне определённых ролей,
однако они связаны с конкретными технологиями, поэтому их описания приводятся
не здесь, а в соответствтвующих разделах.
Всем участникам ADT стоит взаимодействовать
с внешним миром и привлекать к проекту новых участников.
Как стать участником проекта
----------------------------
* Чтобы стать автором ADT, достаточно скопировать свои (или даже чужие, но
распространяемые свободно) тексты в репозиторий исходных текстов
ADT. Подробнее см. раздел @Репозиторий исходных текстов@.
* Чтобы стать сопровождающим ADT, достаточно сделать из документа, имеющегося
в репозитории исходных текстов ADT, модуль документации и
разместить его в репозитории модулей. Подробнее см. раздел(?модули).
* Чтобы стать редактором ADT, достаточно предложить правку в BTS
на любой из модулей документации. Подробнее см. раздел(?BTS).
* Чтобы стать выпускающим, достаточно иметь идею, как сделать выпуск на основе
материалов ADT, поддержку сообщества ADT и время на то, чтобы этим заниматься.
* Чтобы стать ответственным редактором, достаточно, чтобы Вас на эту роль
назначил выпускающий.
2. Репозиторий исходных текстов
===============================
Репозиторий исходных текстов нужен затем, чтобы создать обозримое
поле текстов, над которыми работают или собираются работать участники
ADT.
* Репозиторий исходных текстов должен быть централизованным, чтобы процесс
разработки мог быть совместным и полностью открытым.
* Репозиторий исходных текстов должен быть доступен для открытого просмотра --
это позволит участникам и желающим присоединиться к проекту сориентироваться в
имеющихся материалах и свободно получать исходные тексты для дальнейшей
работы. О доступе на чтение репозитория см. @Чтение репозитория
исходных текстов@.
* Операция записи в репозиторий исходных текстов требует идентификации,
поскольку представивший текст всё-таки несёт некоторую ответственность. О
доступе к репозиторию на запись см. @Запись в репозиторий исходных текстов@.
* Тексты в репозитории исходных текстов должны быть свободно
распространяемыми.
* Тексты в репозитории исходных текстов должны быть классифицированы: это
позволит легче ориентироваться в том, на какие темы есть материалы. О
классификации текстов см. @Классификация документов@.
* Тексты в репозитории исходных текстов должны сопровождаться паспортом,
содержащим сведения, необходимые для дальнейшей работы с текстом в рамках ADT.
О формате и содержимом паспорта текста см. раздел @Паспорт документа@.
Помещает тексты в репозиторий исходных текстов ``Автор'' (см. раздел @Участники проекта@).
Чтение репозитория исходных текстов
-----------------------------------
2all: Нужно придумать, как это организовать.
Запись в репозиторий исходных текстов
-------------------------------------
Чтобы получить доступ на запись в репозиторий исходных текстов (стать
``Автором''), прежде всего нужно написать по адресу joindocs at
altlinux.ru о тех текстах, которые Вы хотели бы добавить в репозиторий ADT
(кратко, но убедительно). В этом письме должна присутствовать информация,
необходимая для организации доступа:
* Идентификатор Автора (полное имя и псевдоним) -- будет использован для
авторизации при записи в репозиторий исходных текстов и для идентификации его
текстов в репозитории исходных текстов. Не должен совпадать с уже
существующими именами.
* Действительный e-mail Автора, по которому члены ADT могут с ним связаться
по поводу его текстов.
* Специально созданный OpenSSH-ключ (DSA, 2048 бит). На joindocs@ высылается
публичная часть ключа. Этот ключ потребуется для помещения пакетов
в репозиторий исходных текстов.
Сгенерировать SSH-ключ можно комадной ssh-keygen -t dsa -b 2048 -f {файл_с_ключом}, подставив на место {файл_с_ключом} имя файла. Настоятельно
рекомендуется сделать ключ с паролем. На joindocs@ следует выслать
публичную часть ключа (файл с расширением .pub).
Решение о предоставлении доступа и вся необходимая дальнейшая информация
будут отправлены на адрес, указанный в письме Автора.
Получив доступ, можно подготовить пакет с текстом(ами) для копирования
в репозиторий. Этот пакет должен соответствовать требованиям, описанным
в разделе @Формат пакета@.
Напрямую поместить пакет в репозиторий исходных текстов невозможно, его нужно
отправить в ``точку входа'' -- incoming/docs. Для этого нужно сначала получить
доступ на запись к репозиторию исходных текстов, как это описано выше.
Incoming/docs -- это временное пристанище, где хранятся вновь поступившие
пакеты, пока они не будут проверены на соответствие правилам оформления.
Неправильно оформленный пакет (отсутствует или оформлен не по правиламш
паспорт, есть конфликт по имени с уже существующим пакетом и т. п.) не будет
принят к размещению в репозитории исходных текстов, а его отправитель получит
письмо с сообщением об ошибках. Прошедшие проверку пакеты размещаются
в репозитории исходных текстов.
Получив доступ (учётную запись вида in_{входное_имя}), потребуется добавить в файл ~/.ssh/config
Host incoming
HostName cvs.altlinux.org
User in_{имя}
Protocol 2
ForwardX11 no
ForwardAgent no
Compression no
Пакет для репозитория исходных текстов (*.tar.gz) необходимо поместить
в каталог incoming:/incoming/docs. Для этого лучше всего использовать
rsync. Команда для копирования пакета в incoming/docs может выглядеть так:
rsync -va --partial --stats -e ssh {имя_файла_пакета} incoming:/incoming/docs/
Если что-то непонятно или не получается, пишите на joindocs@ или в
список рассылки ADT (см. раздел @Список рассылки@).
Формат пакета
-------------
В репозиторий исходных текстов ADT принимаются пакеты с текстами,
оформленные по следующим правилам:
* Все файлы собраны в единый файловый архив в формате .tar.gz. Имя файла может
быть произвольным, но должно быть записано латиницей и желательно, чтобы оно
что-то говорило о содержащемся в файле документе. Нельзя помещать в
репозиторий разные документы под одним и тем же именем.
* В этом файловом архиве содержится (не вложенный ни в какой подкаталог)
файл docinfo, содержащий краткий паспорт документа. Правила оформления
паспорта см. в разделе @Паспорт документа@.
* В этом файловом архиве содержится (не вложенный ни в какой подкаталог)
файл License, в котором описаны условия распространения документа или указано
название и версия лицензии, под которой распространяется документ.
Паспорт документа
-----------------
Паспорт документа для репозитория исходных текстов находится в файле docinfo в
текстовом формате. Формат паспорта прост: он состоит из полей, каждое поле вида
"{название_поля}: данные" и должно занимать одну строку. Все поля должны быть
заполнены, пустое поле считается ошибочным. Список полей:
Title: {название_документа}
{название_документа} без ограничений.
Language: {язык_документа}
Язык должен быть указан в виде стандартного двухбуквенного кода.
Если указан язык, отличный от английского, паспорт документа
должен быть в указанной ниже кодировке (соответственно языку):
Английский en ascii
Русский ru koi8-r
Укаинский uk koi8-u
Authors: {авторы_документа}
Список авторов документа вида {Имя Фамилия}, через запятую.
Имена авторов должны быть записаны по правилам языка документа.
License: {условия_распространения}
Поле {условия_распространения} может содержать одну из следующих
строк:
Строка Значение
------ --------------------------
GPL GNU General Public License
FDL Free Documentation License
distributable Документ можно свободно распространять,
обычно с соблюдением каких-то условий.
Версии лицензий или точные условия распространения документа
указываются в файле License в составе пакета, см. раздел @Формат
пакета@.
Url: {url_исходного_документа}
URL, по которому можно найти исходный документ.
Format: {формат_документа}
Формат, в котором представлен документ. Если он представлен в
нескольких форматах -- список через запятую.
Abstract: {аннотация}
Краткая (в один абзац) аннотация к документу, из которой должно
быть понятно, о чём он, в чём его специфика и какова ценность.
Section: {классификация_документа}
Классификация документа в соответствии с принципами, описанными
в разделе @Классификация документов@. Значения поля Section: содержит
только одну категорию, зато само поле может присутствовать в паспороте
столько раз, сколько требуется указать категорий для текста.
Supported: yes/no
Является ли документ поддерживаемым, т. е. будет ли Автор
отвечать на предложения и вопросы по тексту, направленные
участниками ATD.
Updated: yes/no
Является ли документ обновляемым, т. е. будет ли Автор регулярно
отправлять в репозиторий исходных текстов новый пакет по мере
появляения новой версии документа.
Итого 10 полей. На их заполнение уйдёт совсем немного времени.
Классификация документов
------------------------
Классификация документов при помещении в репозиторий исходных текстов нужна,
чтобы он представлял собой не просто ``Кучу'', из выпускающие, сопровождающие
и остальная публика могли легко находить и просматривать тексты на
интересующие их темы.
Классификация включает 5 признаков, в каждом из которых 3--8 классов.
Желательно (хотя и не обязательно), чтобы по каждому из признаков документ был
отнесён хотя бы к одному классу. Можно отнести документ сразу к нескольким
классам по любому признаку. Если по данному признаку документ не отнесён ни к
какому классу, он автоматически попадает в класс ``Прочее''. Если документ
не охарактеризован ни по одному признаку, он не будет принят к размещению в
репозитории исходных текстов.
Список классов:
Уровень изложения
* Научно-популярный
* Пользовательский
* Профессиональный
Тип документа
* Инструкция
* Документация
* Декларация
Тип решения
* Персональное
* Сервисное
* Общественное
Тип объекта (тема документа)
* Тексты и гипертексты
* Мультимедиа
* Программы
* Хранение и переработка данных
* Бизнес
* Сеть
* Обслуживание и безопасность
* Аппаратное обеспечение
Специфичность
* ALT
* UNIX/POSIX
* Мультиплатформенный
Чтобы включить документ в любую из категорий, достаточно указать в его
паспорте строку:
Section: {название_категории}
Таких строк в паспорте может быть сколько угодно. Пояснения даны ниже.
Уровень изложения
.................
2all: нуждается в комментариях?
* Научно-популярный
* Пользовательский
* Профессиональный
Тип документа
.............
Инструкция
Документы в стиле ``Как'', предназначенные для оперативного или
неквалифицированного снятия проблем (без объяснений или с объяснением,
куда пойти и что почитать).
- тренинг и справочники в стиле ``проблема -- решение''
(например, руководство оператора или секретарши);
- разовые или пошаговые действия (напр., руководство
по установке);
- оперативные ответы на вопросы (HOWTO);
- пямятки, шпаргалки, сводные таблицы и т. п.
Документация
Документы в стиле ``Как и Почему'' (порядок любой, но и то, и другое
должно наличествовать), предназначенные для того, чтобы раз и навсегда
объяснить читателю, в чём дело, и чтобы он глупых вопросов больше не
задавал.
- методички (это близко к ``Как'', но пользователь должен
уйти с чувством, что всё понял);
- примеры решения хитрых или, наоборот, типовых задач
хитрыми инструментами (нечто среднее между предыдущим
и следующим пунктом);
- ответы на вопросы ``Почему'';
- учебники...
Декларация
Документ в стиле ``Why'' или ``What'', то есть описывающий что-то
без цели научить, разве только поставить в известность или убедить.
- полиси и правила;
- форматы;
- реклама, демонстрации, презентации;
- гуманитарные тексты о разработке ПО и компьютерах:
сообщество, феномен свободного ПО, экономические и
правовые модели и т. п.
- всяческие манифесты, лицензии, общественные договоры...
Публикация
Всё, что показалось достойным публикации в ADT, но не вписывается
в предложенные выше категории.
Тип решения
...........
2all: помогите откомментировать
* Персональное
* Сервисное
* Общественное
Тип объекта
...........
Тексты и гипертексты
Объекты, которые читают: документы, www, news и т. п.
Мультимедиа
Объекты, которые воспринимают любым другим способом: нюхают,
лижут, слушают, любуются и т. п.
Программы
Объекты, которые сами работают: программирование, серверы
приложений.
Хранение и переработка данных
Прочие неклассифицированные объекты: базы данных, в основном.
Бизнес
Компьютер как средство организации труда.
Сеть
Объекты передаются по сети.
Обслуживание и безопасность
Объект -- сам компьютер!
Аппаратное обеспечение
Компьютер -- это куча металлолома!
Компьютер
Эта категория -- для всех, кто не вписался ни в одну из прочих.
Указывать её одновременно хотя бы с одной из оставшихся не имеет
смысла.
Специфичность
.............
* ALT
В документе содержатся сведения, специфичные для проектов ALT.
* UNIX/POSIX
В документе содержатся сведения, специфичные для UNIX-совместимых
систем (стандарт POSIX). Linux сюда относится.
* Многоплатформенный
Документ описывает многоплатформенные ПО и решения.
Подробная информация о списке рассылки docs