Создание документации
Материал из ALT Linux Wiki
(→Электронная документация) |
|||
(67 промежуточных версий не показаны.) | |||
Строка 5: | Строка 5: | ||
<!-- | <!-- | ||
1. единственное, что нужно по максимуму давать ссылки на существующие сейчас ресурсы и документы (все, включая heap и тп) с пояснением их текущего статуса (используются: не используются) | 1. единственное, что нужно по максимуму давать ссылки на существующие сейчас ресурсы и документы (все, включая heap и тп) с пояснением их текущего статуса (используются: не используются) | ||
- | |||
--> | --> | ||
== Документация в репозитории/дистрибутивах == | == Документация в репозитории/дистрибутивах == | ||
- | В рамках проекта создаётся документация, призванная помочь пользователям в освоении Linux. | + | В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении Linux. |
- | + | ||
- | + | {{Note|Документация должна быть корректно написана и структурирована, и НЕ должна ориентироваться на способ публикации, печатный или сетевой.}} | |
+ | |||
+ | Коллективное обсуждение всех вопросов, касающихся документации, происходит в списке рассылки [https://lists.altlinux.org/mailman/listinfo/docs docs@]. | ||
=== Печатная документация === | === Печатная документация === | ||
- | Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux в виде брошюр, руководств и т.п. | + | Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux, в виде брошюр, руководств и т. п. |
- | Другой вид печатной документации | + | Другой вид печатной документации — отдельные книги, учебники и т. п. |
+ | |||
+ | Как правило, печатная документация составляется на основе существующей электронной. | ||
- | + | [[printed_docs|Краткая инструкция]] по сборке печатной документации. | |
=== Электронная документация === | === Электронная документация === | ||
- | + | Главное в документации — это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в двух видах: | |
* '''Текст''' | * '''Текст''' | ||
Строка 27: | Строка 30: | ||
: Текст может писаться с нуля, или заимствоваться из сторонних легальных источников. | : Текст может писаться с нуля, или заимствоваться из сторонних легальных источников. | ||
: Технически может представлять из себя файл(ы) в любом читабельном формате: txt, odt, pdf, html | : Технически может представлять из себя файл(ы) в любом читабельном формате: txt, odt, pdf, html | ||
- | |||
- | |||
- | |||
- | |||
* '''rpm-пакет''' | * '''rpm-пакет''' | ||
- | : Это опакеченный в соответствии с принятыми правилами упаковки документации | + | : Это пакет документации опакеченный в соответствии с принятыми правилами упаковки документации |
: В этом виде документация может быть легко установлена в систему. | : В этом виде документация может быть легко установлена в систему. | ||
Таки образом имеем: | Таки образом имеем: | ||
* Текст в любом читабельном формате | * Текст в любом читабельном формате | ||
- | + | * rpm-пакет = текст + spec | |
- | * rpm-пакет = | + | |
- | + | == Пакет электронной документации == | |
- | + | ||
- | + | Электронная документация в виде rpm-пакета присутствует в репозиториях/дистрибутивах. | |
- | + | Документация может описывать процесс установки дистрибутива, обзор приложений, входящих в дистрибутив, руководсво по установке дополнительного ПО. | |
- | + | Процедура опакечевания документации максимально автоматизированна, при условии использования соответствующих инструментов. | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | Пример: [http://sisyphus.ru/ru/srpm/Sisyphus/docs-simply-linux docs-simply-linux] | |
- | + | === Форматы электронной документации === | |
- | + | После установки rpm-пакета, электронная документация присутствует в установленной системе в виде html-файлов. Причём результирующий html, генерируется в процессе сборки из одного из поддерживаемых исходных форматов. Если формат исходного текст пока не поддерживается системой сборки, то генерируется html-страничка, содержащая ссылку на исходный файл в его оригинальном виде. | |
- | + | ||
- | + | Принципиально, оригинальный текст может создаваться в любом формате. Однако существует несколько форматов, для которых поддерживается конвертация в html, что особенно удобно для опакеченной документации. | |
- | + | ||
+ | Документация создаётся разработчиком в одном из поддерживаемых форматов: | ||
* html | * html | ||
:Описание формата: http://www.w3.org/html/ | :Описание формата: http://www.w3.org/html/ | ||
* docbook | * docbook | ||
:Описание формата: http://www.docbook.org/specs/ | :Описание формата: http://www.docbook.org/specs/ | ||
- | |||
- | |||
- | Генерация html происходит в момент создания | + | Генерация html происходит в момент создания rpm-пакета. |
- | + | Процесс опакечивания автоматизирован описан в разделе XXX. | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
== Цикл разработки == | == Цикл разработки == | ||
Строка 97: | Строка 73: | ||
== Инструменты документатора == | == Инструменты документатора == | ||
- | 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