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

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

Текущая версия от 14:38, 6 июля 2023

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

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

В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении 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: Дистрибутивы, компания (в англоязычных текстах);
Basealt SPO: Basealt Ltd. (компания «Базальт СПО» в англоязычных текстах);

ОС "Альт": Операционные системы "Альт";

Репозиторий: Данное слово пишется через "о". Следует запомнить написание этих слов: депозитарий, но репозиторий.

Исторический раздел

Тут будет информация, описывающая для архивных целей технологии, использовавшиеся ранее при работе с документацией в рамках проекта.

Основной источник информации: heap.altlinux.org

Категории:

@@ Строка 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
-* '''Модуль'''
+* '''rpm-пакет'''
-: Это [[#Паспортизация документации|паспортизированный]] '''текст'''. Добавляются 2 файла: [[#Формат файла docinfo|docinfo]] и [[#Формат файла License|License]]
+: Это пакет документации опакеченный в соответствии с принятыми правилами упаковки документации
-: Паспортизация позволяет хранить метаинформацию о тексте, необходимую для архивирования, поиска и т. п.
-: В таком виде документацию уже можно граздо удобнее сортировать и публиковать online
-: Такая попытка сделана на:  http://heap.altlinux.org/
-: Наброски на тему автоматического публикатор документации online: [[ALT_Linux_Wiki:Heap]]
-* '''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]
-* '''модулей''' (rpm-модуль)
-:Модуль представляет из себя опакеченный текст, и соответственно раскрывает в той либо иной степени определённую тему. Например модуль может описывать процесс установки дополнительного ПО.
-:Прцедура опакечевания модулей максимально автоматизированна, при условии использования соответствующих инструментов.
-:Пример: [http://sisyphus.ru/srpm/Sisyphus/docs-packages_apt docs-packages_apt]
-* '''выпуска''' (rpm-выпуск)
-:Выпуск не несёт в себе информативной части, а служит лишь для объединения модулей. Выпуск -- это аналог оглавления в печатном издании.
-:Пример: [http://sisyphus.ru/srpm/Sisyphus/docs-issue-server docs-issue-server]
-* '''indexhtml-пакета'''
-:indexhtml-пакеты предоставляют простую html-страничку, которая по умолчанию является домашней для всех браузеров.
-:Такая html-страничка содержит
-#Приветствие
-#Ссылки на наиболее востребованную документацию. Как правило на '''выпуск''' конкретного дистрибутива.
-:Черновик полиси на indexhtml-пакеты: [[Drafts/indexhtml]]
-:Пример: [http://sisyphus.ru/srpm/Sisyphus/indexhtml-sisyphus indexhtml-sisyphus]
 === Форматы электронной документации ===
-После установки rpm-пакетов, электронная документация присутствует в установленной системе в виде html-файлов. Причём результирующий html, генерируется в процессе сборки из одного из поддерживаемых исходных форматов. Если формат исходного текст пока не поддерживается системой сборки, то генерируется html-страничка, содержащая ссылку на исходный файл в его оригинальном виде.
+После установки rpm-пакета, электронная документация присутствует в установленной системе в виде html-файлов. Причём результирующий html, генерируется в процессе сборки из одного из поддерживаемых исходных форматов. Если формат исходного текст пока не поддерживается системой сборки, то генерируется html-страничка, содержащая ссылку на исходный файл в его оригинальном виде.
-* [[#Форматы для модулей|Форматы для модулей]] (rpm-модулей)
-* [[#Форматы для выпусков|Форматы для выпусков]] (rpm-выпусков)
-==== Форматы для модулей ====
 Принципиально, оригинальный текст может создаваться в любом формате. Однако существует несколько форматов, для которых поддерживается конвертация в html, что особенно удобно для опакеченной документации.
-Модули документации создаются разработчиком в одном из поддерживаемых форматов:
+Документация создаётся разработчиком в одном из поддерживаемых форматов:
 * html
 :Описание формата: http://www.w3.org/html/
 * docbook
 :Описание формата: http://www.docbook.org/specs/
-* m-k
-:Описание формата содержится в документации к пакету [http://sisyphus.ru/srpm/Sisyphus/ALDConvert ALDConvert]
-Генерация html происходит в момент создания rpm-пакета. Кроме генерации 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: http://git.or.cz/
-* [[#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 : Дистрибутивы, компания (в англоязычных текстах);
-поэтому длиной в несколько строк).
+;Basealt SPO : Basealt Ltd. (компания «Базальт СПО» в англоязычных текстах);
-Section: textbook
-</pre>
-Обратите внимание: точки после текста в поле Section нет!<br>
-Обратите внимание: поля в файле docinfo должны быть разделены пустыми строками!
-Подробное описание формата файла docinfo: http://heap.altlinux.org/Titlepage/sample.docinfo.html
-== Пример создания модуля документации ==
-* Выбрать один из поддерживаемых [[#Форматы электронной документации|форматов]]
-* Создать паспорт модуля
-: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>
-* Дистрибутивонезависимые модули
-: Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT.
-: В ALT Linux <s>4.0 Server</s> настройка производится ...
-* Linux пишем как Linux, но не Линукс. (Исключение: документация для школ -- ПСПО)
-: Linux не имеет географического центра разработки.
-: <s>Линукс</s> не имеет географического центра разработки.
-=== Глоссарий терминов ===
-Тут будет глоссарий
-[[Руководство_по_написанию_документации]]
+;Репозиторий : Данное слово пишется через "'''о'''". Следует запомнить написание этих слов: депозит'''а'''рий, но репозит'''о'''рий.
 == Исторический раздел ==
-Тут будет информация, описывающая для архивных целей технологии, использовавшиеся ранее при работе с документацией в рамках проекта.
+{{discuss|Тут будет информация, описывающая для архивных целей технологии, использовавшиеся ранее при работе с документацией в рамках проекта.}}
-Основной источник информации: http://heap.altlinux.org/
+Основной источник информации: [http://heap.altlinux.org/ heap.altlinux.org]