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

Материал из ALT Linux Wiki
Перейти к: навигация, поиск
(Документация в репозитории/дистрибутивах)
 
(не показана 31 промежуточная версия 6 участников)
Строка 9: Строка 9:
 
== Документация в репозитории/дистрибутивах ==
 
== Документация в репозитории/дистрибутивах ==
  
В рамках проекта создаётся документация, призванная помочь пользователям в освоении Linux.
+
В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении Linux.
* [[#Печатная документация|Печатная документация]]
 
* [[#Электронная документация|Электронная документация]]
 
  
Коллективное обсуждение всех вопросов, касающихся документации происходит в списке рассылки docs@: https://lists.altlinux.org/mailman/listinfo/docs
+
{{Note|Документация должна быть корректно написана и структурирована, и НЕ должна ориентироваться на способ публикации, печатный или сетевой.}}
 +
 
 +
Коллективное обсуждение всех вопросов, касающихся документации, происходит в списке рассылки [https://lists.altlinux.org/mailman/listinfo/docs docs@].
  
 
=== Печатная документация ===
 
=== Печатная документация ===
Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux в виде брошюр, руководств и т.п.
+
Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux, в виде брошюр, руководств и т. п.
Другой вид печатной документации -- отдельные книги, учебники и т.п.
+
Другой вид печатной документации отдельные книги, учебники и т. п.
 +
 
 +
Как правило, печатная документация составляется на основе существующей электронной.
  
Как правило, печатная документация составляется на основе существующей [[#Электронная документация|электронной]].
+
[[printed_docs|Краткая инструкция]] по сборке печатной документации.
  
 
=== Электронная документация ===
 
=== Электронная документация ===
Главное в документации -- это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в трёх видах:
+
Главное в документации это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в двух видах:
  
 
* '''Текст'''
 
* '''Текст'''
Строка 28: Строка 30:
 
: Текст может писаться с нуля, или заимствоваться из сторонних легальных источников.
 
: Текст может писаться с нуля, или заимствоваться из сторонних легальных источников.
 
: Технически может представлять из себя файл(ы) в любом читабельном формате: txt, odt, pdf, html
 
: Технически может представлять из себя файл(ы) в любом читабельном формате: txt, odt, pdf, html
* '''Модуль''' (придумать другое название, иначе пересекается с rpm-пакетом-модулем)
 
: Это [[#Паспортизация документации|паспортизированный]] '''текст'''. Добавляются 2 файла: [[#Формат файла docinfo|docinfo]] и [[#Формат файла License|License]]
 
: Паспотризация позволяет хранить метаинформацию о тексте, необходимую для архивирования, поиска и т. п.
 
: В таком виде документацию уже можно граздо удобнее сортировать и публиковать online
 
: Такая попытка сделана на:  http://heap.altlinux.org/
 
: Наброски на тему автоматического публикатор документации online: [[ALT_Linux_Wiki:Heap]]
 
 
* '''rpm-пакет'''
 
* '''rpm-пакет'''
: Это опакеченный в соответствии с принятыми правилами упаковки документации '''модуль'''
+
: Это пакет документации опакеченный в соответствии с принятыми правилами упаковки документации
 
: В этом виде документация может быть легко установлена в систему.
 
: В этом виде документация может быть легко установлена в систему.
  
 
Таки образом имеем:
 
Таки образом имеем:
 
* Текст в любом читабельном формате
 
* Текст в любом читабельном формате
* Модуль = Текст + паспорт
+
* rpm-пакет = текст + spec
* rpm-пакет = Текст + паспорт + spec
 
 
 
=== Паспортизация документации ===
 
 
 
Для целей архивного хранения, идентификации, поиска и т. п. тексты электронной документации паспортизируются. К тексту добавляется два дополнительных файла:
 
 
 
* [[#Формат файла docinfo|'''docinfo''']]
 
* [[#Формат файла License|'''License''']]
 
 
 
Паспортизированные тексты именуются '''Модулями''' (дать другое именование). Такие модули гораздо удобнее сортировать, осуществлять поиск, публиковать onlinе и т.п.
 
 
 
==== Формат файла docinfo ====
 
docinfo -- один из двух файлов, необходимых для [[#Паспортизация документации|паспортизации]] документации.
 
Для этого файла используется одноимённый формат <tt>docinfo</tt> — специально придуманный для этой задачи и разработанный так, чтобы быть одновременно человеко- и машинночитаемым. Поскольку в самой документации метаданные могут быть расположены как угодно и вообще отсутствовать, то без такого «заголовка» не обойтись. <tt>docinfo</tt> позволяет хотя бы минимально контролировать наличие всей необходимой для архивирования, поиска и т. п. информации. Метаинформацию можно двух родов:
 
# об авторе, правах, названии и т. п.
 
# классификаторы документа.
 
: Был выдуман закрытый список классификаторов, предложенный к использованию.
 
 
 
Подробное описание поддерживаемых полей в файле docinfo доступно на: http://heap.altlinux.org/Titlepage/sample.docinfo.html
 
 
 
Пример содержимого файла docinfo:
 
<pre>
 
Title: Как самому собрать аппарат
 
Language: ru
 
Author: Иван Купала (перевод)
 
Version: 2.718281828459045
 
License: FDL
 
Url: http://www.example.com/
 
Format: plain text
 
Abstract: Полное руководство по самостоятельной сборке и отладке аппарата с примерами, таблицами истинности и выдержками из интернет-рекламы
 
Supported: yes
 
Updated: yes
 
Section: Научно-популярный
 
Section: Инструкция
 
Section: Персональное
 
Section: Аппаратное обеспечение
 
Section: Многоплатформенный
 
</pre>
 
 
 
==== Формат файла License ====
 
License -- один из двух файлов, необходимых для [[#Паспортизация документации|паспортизации]] документации.
 
Этот файл представляет из себя текстовый файл, содержащий текст лицензии на паспортизируемый текст.
 
  
Пример содержимого файла License:
+
== Пакет электронной документации ==
<pre>
 
Данный документ распространяется на условиях свободной лицензии
 
FDL (Free Documentation License) версии 1.1 или любой более поздней версии.
 
  
Данный документ не содержит текста, помещаемого на первой или последней
+
Электронная документация в виде rpm-пакета присутствует в репозиториях/дистрибутивах.
странице обложки. Данный документ не содержит неизменяемого текста.
 
</pre>
 
  
== Комплект опакеченной электронной документации ==
+
Документация может описывать процесс установки дистрибутива, обзор приложений, входящих в дистрибутив, руководсво по установке дополнительного ПО.
  
Электронная документация в виде rpm-пакетов присутствует в репозиториях/дистрибутивах.
+
Процедура опакечевания документации максимально автоматизированна, при условии использования соответствующих инструментов.
  
Обычно комплект электронной документации состоит из rpm-пакетов:
+
Пример: [http://sisyphus.ru/ru/srpm/Sisyphus/docs-simply-linux docs-simply-linux]
* '''модулей'''
 
:Модуль представляет из себя опакеченный текст, и соответственно раскрывает в той либо иной степени определённую тему. Например модуль может описывать процесс установки дополнительного ПО.
 
:Прцедура опакечевания модулей максимально автоматизированна, при условии использования соответствующих инструментов.
 
:Пример: [http://sisyphus.ru/srpm/Sisyphus/docs-packages_apt docs-packages_apt]
 
* '''выпуска'''
 
:Выпуск не несёт в себе информативной части, а служит лишь для объединения модулей. Выпуск -- это аналог оглавления в печатном издании.
 
:Пример: [http://sisyphus.ru/srpm/Sisyphus/docs-issue-server docs-issue-server]
 
* '''indexhtml-пакета'''
 
:indexhtml-пакеты предоставляют простую html-страничку, которая по умолчанию является домашней для всех браузеров.
 
:Такая html-страничка содержит
 
#Приветствие
 
#Ссылки на наиболее востребованную документацию. Как правило на '''выпуск''' конкретного дистрибутива.
 
:Черновик полиси на indexhtml-пакеты: [[Drafts/indexhtml]]
 
:Пример: [http://sisyphus.ru/srpm/Sisyphus/indexhtml-lite indexhtml-lite]
 
  
 
=== Форматы электронной документации ===
 
=== Форматы электронной документации ===
  
После установки rpm-пакетов, электронная документация присутствует в установленной системе в виде html-файлов. Причём результирующий html, генерируется в процессе сборки из одного из поддерживаемых исходных форматов. Если формат исходного текст пока не поддерживается системой сборки, то генерирутеся html-страничка, содержащая ссылку на исходный файл в его оригинальном виде.
+
После установки rpm-пакета, электронная документация присутствует в установленной системе в виде html-файлов. Причём результирующий 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/
* m-k
 
:Описание формата содержится в документации к пакету [http://sisyphus.ru/srpm/Sisyphus/ALDConvert ALDConvert]
 
  
Генерация html происходит в момент создания '''пакета'''. Этот процесс автоматизирован и описан в разделе Цикл разработки.
+
Генерация html происходит в момент создания rpm-пакета.  
  
==== Форматы для выпусков ====
+
Процесс опакечивания автоматизирован описан в разделе XXX.
Для '''выпусков''' поддерживается только html-формат, расширенный возможностью использовать в ссылках '''adt''':
 
 
 
<source lang="html4strict">
 
<ul>
 
<li><a href="adt:packages_apt">Управление пакетами (APT)</a></li>
 
<li><a href="adt:init_d">Стартовые сценарии</a></li>
 
</ul>
 
</source>
 
 
 
В этом примере в результирующем html автоматически создаются ссылки на модули docs-packages_apt и docs-init_d а в сам пакет выпуска проставляеюся зависимости на эти два модуля.
 
  
 
== Цикл разработки ==
 
== Цикл разработки ==
Строка 156: Строка 73:
 
== Инструменты документатора ==
 
== Инструменты документатора ==
  
git как нельзя лучше подходит для хранения всех трёх видов документации: '''Текстов''' и '''Модулей''' и rpm-пакетов (перефразировть).
+
[http://git.or.cz/ git] как нельзя лучше подходит для хранения документации.
  
Инструменты, облегчающие работу документатора:
+
[http://fedorahosted.org/publican/ Publican] - утилита для создания документации на базе стандарта DocBook. Утилита предназначена для автоматизации и сокращения сроков развертывания и настройки под конкретный проект DocBook-инфраструктуры, операций экспорта в нужные форматы (в том числе PDF и HTML).
* git
 
* [[#rpm-build-docs|rpm-build-docs]]
 
* [[#alt-docs-genextras|alt-docs-genextras]]
 
  
=== rpm-build-docs ===
+
== Пример создания пакета документации ==
  
В пакете rpm-build-docs содержится несколько средств для автоматизации
+
* Выбрать один из поддерживаемых [[#Форматы электронной документации|форматов]]
процесса превращения документа в пакет в Сизифе.
+
* Создать spec-файл
 +
*: При написании [http://www.altlinux.org/Spec spec]-файла следует придерживаться общих правил.  
  
Общая задача — сделать процесс подготовки пакетов максимально
+
=== Требования к пакетам документации ===
автоматизированным, сведя необходимое участие в нём человека
 
к однократному созданию первоначального спека. А последующую
 
пересборку пакета при всех обновлениях самого документа
 
сделать по возможности автоматической.
 
  
В пакет входят следующие компоненты:
+
==== Именование пакетов ====
 +
Пакеты следует именовать по следующей схеме: docs-<''название_дистрибутива''>
  
docs_genspec
+
Группа для указания в spec-файле: Documentation
------------
 
Утилита, которая из указанного архива с документом (из Кучи)
 
вынимает docinfo и на основе данных из него строит типичный спек-файл.
 
Она умеет также обновлять уже имеющийся спек-файл (если он был
 
некогда сгенерён этой же утилитой и не испорчен до неузнаваемости).
 
  
docsbuild
+
Пример:
---------
 
Скрипт, который запускает процесс сборки документации из исходного
 
формата в html. В одном из аргументов ему передаётся название исходного
 
формата. Дальше он смотрит по таблице, какая функция отвечает за сборку
 
из этого формата в html и запускает эту функцию. Принципиально
 
разрабатывался как расширяемый — чтобы легко было добавлять новые
 
функции для сборки html из других форматов.
 
  
Пользователь не должен вручную запускать docsbuild, он запускается при
+
<pre>Name: docs-simply-linux
сборке пакета при помощи rpm-макроса, которому docs_genspec проставит нужные
 
аргументы. У пользователя остаётся возможность добавить в спеке этому
 
макросу любые дополнительные параметры для сборки (Естественно, их
 
должна понимать сборочная функция для этого формата).
 
  
RPM-макросы
+
Group: Documentation</pre>
-----------
 
Нужны для того, чтобы не повторять стандартные операции в каждом спеке.
 
Кроме того, последовательное использование макросов позволит при любых
 
изменениях в этих стандартных операциях (то есть в сборочной среде)
 
''автоматически'' пересобирать пакеты с документацией, ''ничего'' не изменяя
 
в самих спеках (то есть полностью без вмешательства человека).
 
  
=== alt-docs-genextras ===
+
==== Каталог установки ====
  
В ALT Linux предусмотрена стандартизованная процедура для
+
Файлы пакета документации (html, стили, логотипы и т. п.) устанавливаются в каталог /usr/share/doc/documentation/
включения вновь установленных выпусков документации  
 
в общую структуру электронной документации.
 
  
Сценарий alt-docs-genextras, находящийся в данном пакете
+
==== Конфликты ====
служит для автоматической генерации и обновления списка
+
Так как пакеты документации устанавливают свои файлы в один и тот же каталог, в системе не должно одновременно присутствовать более одного пакета документации.
ссылок на установленные выпуски документации (пакеты docs-issue-*)
+
Для обеспечения этого пакеты должны иметь конфликты на каждый docs-distro пакет, то есть содержать в своём spec-файле:
на главной странице документации ALT Linux (пакет alt-docs-main).
 
  
Этот сценарий вызывается после установки и удаления любого выпуска
+
<pre>Cоnflicts: docs-firstdistro, docs-seconddistro, docs-thirddistro</pre>
документации, для удобства есть rpm-макросы, находящиеся в пакете
 
rpm-build-docs.
 
  
Информация о пакете (файл docinfo)
+
== Соглашения при написании документации ==
 +
* Ссылки на сайты даются с указанием завершающего слэша:
 +
*: <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>
 +
* В заголовках статей и разделов точки ставить не нужно
 +
* В списках в конце перечислений лучше ставить точку с запятой
  
Текст ссылок, размещаемых на главной странице документации,
+
=== Множественное число и использование акронимов со словом «сервер» ===
автоматически генерируется на основании файла docinfo.
 
По умолчанию такие файлы ищутся  в подкаталогах
 
/usr/share/doc/alt-docs/.
 
  
Если файл docinfo содержит русскоязычный текст (что предполагается),
+
Множественное число в именительном падеже — '''серверы'''. [http://gramota.ru/spravka/buro/29_332846]
он должен быть в кодировке koi8-r!                                 
 
  
В файле docinfo должна содержаться следующая информация:
+
Сервер (кроме названий продуктов) — через дефис, после сокращения: ''DHCP-сервер, RAS-сервер, OLE-сервер''.
  
* '''Title: Название документа'''
+
Сервер (с названием продукта) — перед сокращением: ''сервер UNIX, сервер Windows''. [http://www.microsoft.com/downloads/details.aspx?familyid=25018024-2DFD-4229-9763-05F78FEAF2FF&displaylang=en]
:Название будет текстом гиперссылки на стартовую страницу документа (index.html).
 
* '''Abstract: Аннотация документа.'''
 
:Этот текст будет включён в оглавление и должен давать представление о тематике документа и о том, для кого он предназначен (опытный пользователь, новичок, любознательный и т. п.). Строгих требований к аннотации нет, но из неё читатель должен иметь возможность понять, что это за документ и нужно ли ему его читать.<br>Допустимо и даже желательно, чтобы краткое описание пакета (поле %description -l ru_RU.KOI8-R в spec-файле пакета) совпадало с аннотацией.
 
* '''Section:  Тематическая рубрика.'''
 
:Тематическая рубрика, в которую нужно поместить ссылку. В настоящее время пакет для помещения на главную страницу документации (alt-docs-main) здесь должно быть значение ''distrib''. Другие значения игнорируются.
 
  
Текущий формат файла docinfo таков:
+
Возможно и написание ''сервер FTP''. [http://lists.kde.ru/pipermail/kde-russian/2008-August/008019.html]
  
<pre>
+
=== Глоссарий терминов ===
Section: Название документа
 
  
Abstract: Аннотация документа (достаточно информативная,
+
* ALT Linux — дистрибутивы
поэтому длиной в несколько строк).
+
* ALT Linux — компания англоязычных текстах)
 +
* Компания «Альт Линукс», ООО «Альт Линукс», ООО «Альт Линукс Технолоджи»
  
Section: textbook
+
[[Руководство_по_написанию_документации]]
</pre>
 
  
Обратите внимание: точки после текста в поле Section нет!<br>
+
== Исторический раздел ==
Обратите внимание: поля в файле docinfo должны быть разделены пустыми строками!
 
  
Подробное описание формата файла docinfo: http://heap.altlinux.org/Titlepage/sample.docinfo.html
+
{{discuss|Тут будет информация, описывающая для архивных целей технологии, использовавшиеся ранее при работе с документацией в рамках проекта.}}
  
== Пример создания модуля документации ==
+
Основной источник информации: [http://heap.altlinux.org/ heap.altlinux.org]
 
 
* Выбрать один из поддерживаемых [[#Форматы электронной документации|форматов]]
 
* Создать паспорт модуля
 
:docinfo-файл с синтаксисом,
 
* Создать spec-файл
 
:При написании spec-файла следует придерживаться общих правил. (Дать ссылку).
 
 
 
Шаблоны docinfo-файла и spec-файла можно взять c http://git.altlinux.org/ (Дать точную ссылку)
 
 
 
== Cоглашения при написании документации ==
 
* Ссылки на сайты даются с указанием завершающего слэша
 
:<nowiki>http://www.altlinux.ru/</nowiki> <s><nowiki>http://www.altlinux.ru</nowiki></s>
 
* Буква '''ё''' используется. [http://python.anabar.ru/yo.htm Скрипт для полуавтоматической расстановки букв ё в тексте].
 
* Обращение '''вы''' пишем со строчной
 
:Обращаем ваше внимание
 
:<s>Обращаем Ваше внимание</s>
 
 
 
=== Глоссарий терминов ===
 
Тут будет глоссарий
 
 
 
[[Руководство_по_написанию_документации]]
 

Текущая версия на 13:18, 9 февраля 2017

Stub.png
Данная страница находится в разработке.
Эта страница ещё не закончена. Информация, представленная здесь, может оказаться неполной или неверной.


Документация в репозитории/дистрибутивах[править]

В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении 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