Создание документации: различия между версиями

Материал из ALT Linux Wiki

Версия от 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.ru~~ http://www.altlinux.ru/
Буква ё используется:
Скрипт для полуавтоматической расстановки букв ё в тексте.
Обращение вы пишем со строчной:
Обращаем ~~Ваше~~ ваше внимание …
Дистрибутивонезависимые модули. Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT.
В ALT Linux ~~4.0 Server~~ настройка производится …
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

Категории:

@@ Строка 1: / Строка 1: @@
-== Описание процесса создания документации ==
+{{Stub}}
-=== Документация в репозитории/дистрибутивах ===
+[[Категория:Документирование]]
-В рамках проекта создаётся документация, призванная помочь пользователям в освоении Linux.
+<!--
+. единственное, что нужно по максимуму давать ссылки на существующие сейчас ресурсы и документы (все, включая heap и тп) с пояснением их текущего статуса (используются: не используются)
+-->
-Печатная документация прилагается к готовым дистрибутивам.
+== Документация в репозитории/дистрибутивах ==
-Электронная документация в виде rpm-пакетов присутствует в репозиториях.
+В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении Linux.
-Комплект электронной документации состоит из отдельных '''модулей''', которые объединены '''выпуском'''.
+{{Note|Документация должна быть корректно написана и структурирована, и НЕ должна ориентироваться на способ публикации, печатный или сетевой.}}
-Модуль представляет из себя самодостаточный текст, раскрывающий в той либо иной степени определённую тему. Например модуль может описывать процесс установки дополнительного ПО.
+Коллективное обсуждение всех вопросов, касающихся документации, происходит в списке рассылки [https://lists.altlinux.org/mailman/listinfo/docs docs@].
-Выпуск не несёт в себе информативной части, а служит лишь для объединения модулей.
+=== Печатная документация ===
+Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux, в виде брошюр, руководств и т. п.
+Другой вид печатной документации — отдельные книги, учебники и т. п.
-Аналогия: Фалы и Каталоги
+Как правило, печатная документация составляется на основе существующей электронной.
-=== Форматы документации ===
+[[printed_docs|Краткая инструкция]] по сборке печатной документации.
+=== Электронная документация ===
+Главное в документации — это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в двух видах:
-html
+* '''Текст'''
-pfd
+: Минимальная форма хранения информации.
-m-k
+: Текст может писаться с нуля, или заимствоваться из сторонних легальных источников.
+: Технически может представлять из себя файл(ы) в любом читабельном формате: txt, odt, pdf, html
+* '''rpm-пакет'''
+: Это пакет документации опакеченный в соответствии с принятыми правилами упаковки документации
+: В этом виде документация может быть легко установлена в систему.
-=== Цикл разработки ===
+Таки образом имеем:
+* Текст в любом читабельном формате
+* rpm-пакет = текст + spec
-git
+== Пакет электронной документации ==
-пакет
-репозиторий
+Электронная документация в виде rpm-пакета присутствует в репозиториях/дистрибутивах.
-=== Инструменты документатора ===
+Документация может описывать процесс установки дистрибутива, обзор приложений, входящих в дистрибутив, руководсво по установке дополнительного ПО.
-git, rpm-build-docs ...
+Процедура опакечевания документации максимально автоматизированна, при условии использования соответствующих инструментов.
+Пример: [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]