Создание документации
Материал из ALT Linux Wiki
(Различия между версиями)
(→Инструменты документатора) |
|||
| (104 промежуточные версии не показаны) | |||
| Строка 1: | Строка 1: | ||
| - | + | {{Stub}} | |
| - | + | [[Категория:Документирование]] | |
| - | + | <!-- | |
| + | 1. единственное, что нужно по максимуму давать ссылки на существующие сейчас ресурсы и документы (все, включая heap и тп) с пояснением их текущего статуса (используются: не используются) | ||
| + | --> | ||
| - | ==== | + | == Документация в репозитории/дистрибутивах == |
| - | + | ||
| - | + | ||
| - | + | В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении Linux. | |
| - | + | ||
| - | + | ||
| - | + | {{Note|Документация должна быть корректно написана и структурирована, и НЕ должна ориентироваться на способ публикации, печатный или сетевой.}} | |
| - | + | Коллективное обсуждение всех вопросов, касающихся документации, происходит в списке рассылки [https://lists.altlinux.org/mailman/listinfo/docs docs@]. | |
| - | + | === Печатная документация === | |
| + | Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux, в виде брошюр, руководств и т. п. | ||
| + | Другой вид печатной документации — отдельные книги, учебники и т. п. | ||
| - | + | Как правило, печатная документация составляется на основе существующей электронной. | |
| - | + | [[printed_docs|Краткая инструкция]] по сборке печатной документации. | |
| - | Электронная документация | + | === Электронная документация === |
| + | Главное в документации — это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в двух видах: | ||
| - | + | * '''Текст''' | |
| + | : Минимальная форма хранения информации. | ||
| + | : Текст может писаться с нуля, или заимствоваться из сторонних легальных источников. | ||
| + | : Технически может представлять из себя файл(ы) в любом читабельном формате: txt, odt, pdf, html | ||
| + | * '''rpm-пакет''' | ||
| + | : Это пакет документации опакеченный в соответствии с принятыми правилами упаковки документации | ||
| + | : В этом виде документация может быть легко установлена в систему. | ||
| - | = | + | Таки образом имеем: |
| + | * Текст в любом читабельном формате | ||
| + | * rpm-пакет = текст + spec | ||
| - | + | == Пакет электронной документации == | |
| - | + | ||
| - | + | ||
| + | Электронная документация в виде rpm-пакета присутствует в репозиториях/дистрибутивах. | ||
| - | + | Документация может описывать процесс установки дистрибутива, обзор приложений, входящих в дистрибутив, руководсво по установке дополнительного ПО. | |
| - | + | Процедура опакечевания документации максимально автоматизированна, при условии использования соответствующих инструментов. | |
| - | + | Пример: [http://sisyphus.ru/ru/srpm/Sisyphus/docs-simply-linux docs-simply-linux] | |
| - | + | === Форматы электронной документации === | |
| - | + | ||
| - | + | После установки rpm-пакета, электронная документация присутствует в установленной системе в виде html-файлов. Причём результирующий html, генерируется в процессе сборки из одного из поддерживаемых исходных форматов. Если формат исходного текст пока не поддерживается системой сборки, то генерируется html-страничка, содержащая ссылку на исходный файл в его оригинальном виде. | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | Принципиально, оригинальный текст может создаваться в любом формате. Однако существует несколько форматов, для которых поддерживается конвертация в html, что особенно удобно для опакеченной документации. | |
| - | + | Документация создаётся разработчиком в одном из поддерживаемых форматов: | |
| - | + | * html | |
| - | + | :Описание формата: http://www.w3.org/html/ | |
| - | + | * docbook | |
| - | + | :Описание формата: http://www.docbook.org/specs/ | |
| - | + | ||
| - | + | Генерация html происходит в момент создания rpm-пакета. | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | Процесс опакечивания автоматизирован описан в разделе XXX. | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | == Цикл разработки == | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | * Тексты коллективно создаются и модифицируются в git.altlinux.org | |
| + | :При этом git используется не только при создании текстов с нуля, но и при опакечивании сторонних текстов. | ||
| + | * При необходимости создаются пакеты | ||
| + | * Пакеты оказываются в нужном репозитории | ||
| - | + | == Инструменты документатора == | |
| - | + | ||
| - | + | ||
| - | + | [http://git.or.cz/ git] как нельзя лучше подходит для хранения документации. | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | [http://fedorahosted.org/publican/ Publican] - утилита для создания документации на базе стандарта DocBook. Утилита предназначена для автоматизации и сокращения сроков развертывания и настройки под конкретный проект DocBook-инфраструктуры, операций экспорта в нужные форматы (в том числе PDF и HTML). | |
| - | документации | + | |
| - | + | ||
| - | + | == Пример создания пакета документации == | |
| - | + | * Выбрать один из поддерживаемых [[#Форматы электронной документации|форматов]] | |
| - | + | * Создать spec-файл | |
| - | + | *: При написании [http://www.altlinux.org/Spec spec]-файла следует придерживаться общих правил. | |
| - | / | + | |
| - | + | === Требования к пакетам документации === | |
| - | + | ||
| - | + | ==== Именование пакетов ==== | |
| + | Пакеты следует именовать по следующей схеме: docs-<''название_дистрибутива''> | ||
| - | + | Группа для указания в spec-файле: Documentation | |
| - | + | ||
| - | + | Пример: | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | <pre>Name: docs-simply-linux | |
| - | + | Group: Documentation</pre> | |
| - | + | ||
| - | + | ==== Каталог установки ==== | |
| - | + | ||
| - | + | Файлы пакета документации (html, стили, логотипы и т. п.) устанавливаются в каталог /usr/share/doc/documentation/ | |
| - | + | ||
| - | + | ||
| - | + | ||
| + | ==== Конфликты ==== | ||
| + | Так как пакеты документации устанавливают свои файлы в один и тот же каталог, в системе не должно одновременно присутствовать более одного пакета документации. | ||
| + | Для обеспечения этого пакеты должны иметь конфликты на каждый docs-distro пакет, то есть содержать в своём spec-файле: | ||
| + | <pre>Cоnflicts: docs-firstdistro, docs-seconddistro, docs-thirddistro</pre> | ||
| - | ==== | + | == Соглашения при написании документации == |
| + | * Ссылки на сайты даются с указанием завершающего слэша: | ||
| + | *: <s><nowiki>http://www.altlinux.ru</nowiki></s> <nowiki>http://www.altlinux.ru/</nowiki> | ||
| + | <!-- *: wiki — <nowiki>http://www.altlinux.org/</nowiki> | ||
| + | *: forum — <nowiki>http://forum.altlinux.org/</nowiki> | ||
| + | *: company — <nowiki>http://altlinux.ru/</nowiki> (уточнить) --> | ||
| + | * Буква '''ё''' используется: | ||
| + | *: [http://python.anabar.ru/yo.htm Скрипт для полуавтоматической расстановки букв ё в тексте]. | ||
| + | * Обращение '''вы''' пишем со строчной: | ||
| + | *: Обращаем <s>Ваше</s> ваше внимание … | ||
| + | * Дистрибутивонезависимые модули. Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT. | ||
| + | *: В ALT Linux <s>4.0 Server</s> настройка производится … | ||
| + | * Linux пишем как Linux, но не Линукс. (Исключение: документация для школ — ПСПО) | ||
| + | *: <s>Линукс</s> Linux не имеет географического центра разработки. | ||
| + | * Желательно следить за тем, чтобы в теги попадали те слова, которые к эти тегам относятся, например, не нужно писать внутри тегов точку или знак деления: | ||
| + | *: который завершается нажатием клавиши <s><nowiki><keycap>Enter.</keycap></nowiki></s> <nowiki><keycap>Enter</keycap>.</nowiki> | ||
| + | * В заголовках статей и разделов точки ставить не нужно | ||
| + | * В списках в конце перечислений лучше ставить точку с запятой | ||
| - | == | + | === Множественное число и использование акронимов со словом «сервер» === |
| + | |||
| + | Множественное число в именительном падеже — '''серверы'''. [http://gramota.ru/spravka/buro/29_332846] | ||
| + | |||
| + | Сервер (кроме названий продуктов) — через дефис, после сокращения: ''DHCP-сервер, RAS-сервер, OLE-сервер''. | ||
| + | |||
| + | Сервер (с названием продукта) — перед сокращением: ''сервер UNIX, сервер Windows''. [http://www.microsoft.com/downloads/details.aspx?familyid=25018024-2DFD-4229-9763-05F78FEAF2FF&displaylang=en] | ||
| + | |||
| + | Возможно и написание ''сервер FTP''. [http://lists.kde.ru/pipermail/kde-russian/2008-August/008019.html] | ||
| + | |||
| + | === Глоссарий терминов === | ||
| + | |||
| + | * ALT Linux — дистрибутивы | ||
| + | * ALT Linux — компания (в англоязычных текстах) | ||
| + | * Компания «Альт Линукс», ООО «Альт Линукс», ООО «Альт Линукс Технолоджи» | ||
| + | |||
| + | [[Руководство_по_написанию_документации]] | ||
| + | |||
| + | == Исторический раздел == | ||
| + | |||
| + | {{discuss|Тут будет информация, описывающая для архивных целей технологии, использовавшиеся ранее при работе с документацией в рамках проекта.}} | ||
| + | |||
| + | Основной источник информации: [http://heap.altlinux.org/ heap.altlinux.org] | ||
Текущая версия на 13:18, 9 февраля 2017
Содержание |
Документация в репозитории/дистрибутивах
В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении 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/
Генерация 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.ruhttp://www.altlinux.ru/
-
- Буква ё используется:
- Обращение вы пишем со строчной:
- Обращаем
Вашеваше внимание …
- Обращаем
- Дистрибутивонезависимые модули. Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT.
- В ALT Linux
4.0 Serverнастройка производится …
- В ALT Linux
- Linux пишем как Linux, но не Линукс. (Исключение: документация для школ — ПСПО)
-
ЛинуксLinux не имеет географического центра разработки.
-
- Желательно следить за тем, чтобы в теги попадали те слова, которые к эти тегам относятся, например, не нужно писать внутри тегов точку или знак деления:
- который завершается нажатием клавиши
<keycap>Enter.</keycap><keycap>Enter</keycap>.
- который завершается нажатием клавиши
- В заголовках статей и разделов точки ставить не нужно
- В списках в конце перечислений лучше ставить точку с запятой
Множественное число и использование акронимов со словом «сервер»
Множественное число в именительном падеже — серверы. [1]
Сервер (кроме названий продуктов) — через дефис, после сокращения: DHCP-сервер, RAS-сервер, OLE-сервер.
Сервер (с названием продукта) — перед сокращением: сервер UNIX, сервер Windows. [2]
Возможно и написание сервер FTP. [3]
Глоссарий терминов
- ALT Linux — дистрибутивы
- ALT Linux — компания (в англоязычных текстах)
- Компания «Альт Линукс», ООО «Альт Линукс», ООО «Альт Линукс Технолоджи»
Руководство_по_написанию_документации
Исторический раздел
Основной источник информации: heap.altlinux.org
