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

Материал из ALT Linux Wiki
(Изменения и дополнения в глоссарии терминов.)
 
(не показано 38 промежуточных версий 8 участников)
Строка 9: Строка 9:
== Документация в репозитории/дистрибутивах ==
== Документация в репозитории/дистрибутивах ==


В рамках проекта создаётся документация, призванная помочь пользователям в освоении Linux.
В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении Linux.
* [[#Печатная документация|Печатная документация]]
 
* [[#Электронная документация|Электронная документация]]
{{Note|Документация должна быть корректно написана и структурирована, и НЕ должна ориентироваться на способ публикации, печатный или сетевой.}}
 
Коллективное обсуждение всех вопросов, касающихся документации, происходит в списке рассылки [https://lists.altlinux.org/mailman/listinfo/docs docs@].


=== Печатная документация ===
=== Печатная документация ===
Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux в виде брошюр, руководств и т.п.
Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux, в виде брошюр, руководств и т. п.
Другой вид печатной документации -- отдельные книги, учебники и т.п.
Другой вид печатной документации — отдельные книги, учебники и т. п.
 
Как правило, печатная документация составляется на основе существующей электронной.


Как правило, печатная документация составляется на основе существующей [[#Электронная документация|электронной]].
[[printed_docs|Краткая инструкция]] по сборке печатной документации.


=== Электронная документация ===
=== Электронная документация ===
Главное в документации -- это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в трёх видах:
Главное в документации — это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в двух видах:


* '''Текст'''
* '''Текст'''
Строка 26: Строка 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:
Электронная документация в виде rpm-пакета присутствует в репозиториях/дистрибутивах.
<pre>
Данный документ распространяется на условиях свободной лицензии
FDL (Free Documentation License) версии 1.1 или любой более поздней версии.


Данный документ не содержит текста, помещаемого на первой или последней
Документация может описывать процесс установки дистрибутива, обзор приложений, входящих в дистрибутив, руководсво по установке дополнительного ПО.
странице обложки. Данный документ не содержит неизменяемого текста.
</pre>


== Комплект опакеченной электронной документации ==
Процедура опакечевания документации максимально автоматизированна, при условии использования соответствующих инструментов.


Электронная документация в виде 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]
* '''выпуска'''
:Выпуск не несёт в себе информативной части, а служит лишь для объединения модулей. Выпуск -- это аналог оглавления в печатном издании.
:Пример: [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]


=== Форматы электронной документации ===
=== Форматы электронной документации ===


Электронная документация присутствует в установленной системе в виде html-файлов. Начальная страница каждого модуля содержит ссылку на '''паспорт''' модуля. Паспорт представляет из себя файл, содержащий различную мета-информацию: Автор, Версия, Тема, Краткое описание. Паспорт позволяет легче ориентироваться в большом количестве модулей.
После установки 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/
* m-k
:Описание формата содержится в документации к пакету [http://sisyphus.ru/srpm/Sisyphus/ALDConvert ALDConvert]
Генерация html происходит в момент создания '''пакета'''. Этот процесс автоматизирован и описан в разделе Цикл разработки.
==== Форматы для выпусков ====
Для '''выпусков''' поддерживается только html-формат, расширенный возможностью использовать в ссылках '''adt''':


<source lang="html4strict">
Генерация html происходит в момент создания rpm-пакета.
<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 а в сам пакет выпуска проставляеюся зависимости на эти два модуля.
Процесс опакечивания автоматизирован описан в разделе XXX.


== Цикл разработки ==
== Цикл разработки ==
Строка 150: Строка 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 : Дистрибутивы, компания (в англоязычных текстах);
поэтому длиной в несколько строк).
;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>


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


[[Руководство_по_написанию_документации]]
Основной источник информации: [http://heap.altlinux.org/ heap.altlinux.org]

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

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

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

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

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