---
description: 'Обзор процесса создания документации FreeBSD'
next: books/fdp-primer/tools
params:
  path: /books/fdp-primer/overview/
prev: books/fdp-primer/preface
showBookMenu: 'true'
tags: ["overview", "FreeBSD Documentation Project", "quick start"]
title: 'Глава 1. Обзор'
weight: 2
---

[[overview]]
= Обзор
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 1
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/fdp-primer/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

Добро пожаловать в Проект документации FreeBSD (FDP). Качественная документация крайне важна для успеха FreeBSD, и мы очень высоко ценим ваш вклад.

Этот документ описывает организацию FDP, как писать и отправлять документацию, а также как эффективно использовать доступные инструменты.

Все желающие могут внести свой вклад в FDP. Готовность помочь — единственное требование для участия.

Это руководство показывает, как:

* Понять роль документации и её место в экосистеме.
* Определите, какие части FreeBSD поддерживаются FDP.
* Установить необходимые инструменты и файлы документации.
* Внести изменения в документацию.
* Представить изменения для проверки и включения в документацию FreeBSD.

[[overview-documentation-ecosystem]]
== Документация в экосистеме FreeBSD

Все документы создаются для пользы читателей, а не их авторов или сопровождающих. Они должны адаптироваться к читателю, а не ожидать, что читатель адаптируется к ним.

Никогда не вините читателя за:

* невозможность легко или вообще использовать документ
* если документ показался ему непонятным
* непонимание документа или того, как его применить
* если он не нашел явный ответ или шаги, чтобы логически прийти к нему

Вместо этого подтвердите, что документ:

* недоступный
* запутанный
* трудно понимаемый или применимый
* неполный

Затем создайте документ:

* более доступный
* менее запутанный
* более ясный
* более полный

Используйте следующие методы:

* Примените link:https://webaim.org/intro/#principles[лучшие практики доступности], чтобы исправить выявленную проблему и любые подобные, которые обнаружите
* переработайте или уточните запутанную структуру или язык
* добавьте соответствующие примеры к части, которая трудна для понимания или применения
* заполните пробелы или добавьте недостающие промежуточные этапы

[[overview-quick-start]]
== Быстрый старт

Некоторые подготовительные шаги необходимо выполнить перед редактированием документации FreeBSD. Сначала подпишитесь на рассылку {freebsd-doc}. Некоторые участники команды также общаются в IRC-канале `#bsddocs` на http://www.efnet.org/[EFnet]. Эти люди могут помочь с вопросами или проблемами, связанными с документацией.

[[freebsd-installation-process]]
=== Процесс установки FreeBSD

[.procedure]
====
. Установите эти пакеты. _Мета-порт_ `docproj` устанавливает все приложения, необходимые для работы с документацией FreeBSD.
+
[source, shell]
....
# pkg install docproj
....
+
. Установите локальную рабочую копию документации из репозитория FreeBSD в [.filename]#~/doc# (см. crossref:working-copy[working-copy,Рабочая копия]).
+
[source, shell]
....
% git clone https://git.FreeBSD.org/doc.git ~/doc
....
+
. Отредактируйте файлы документации, которые требуют изменений. Если файлу нужны значительные изменения, обратитесь за советом в список рассылки.
+
Просмотрите вывод и отредактируйте файл, чтобы исправить указанные проблемы, затем повторно запустите команду для поиска оставшихся проблем. Повторяйте, пока все ошибки не будут устранены.
+
. *_Всегда_* собирайте и проверяйте изменения перед отправкой. Запуск команды `make` в подкаталогах `documentation` или `website` сгенерирует документацию в формате HTML.
+
[source, shell]
....
% make
....
+
Для сокращения времени компиляции может быть скомпилирован только один язык:
+
[source, shell]
....
% make DOC_LANG=en
....
+
Результаты сборки сохраняются в [.filename]#~/doc/documentation/public/en/articles/# и [.filename]#~/doc/documentation/public/en/books/#.
+
. Просмотрите вывод сборки и убедитесь, что правки не содержат опечаток, проблем с версткой или ошибок. Если в процессе сборки обнаружены ошибки, отредактируйте проблемные файлы, чтобы исправить все возникшие проблемы, затем снова запустите команду сборки, пока все ошибки не будут устранены.
+
. Добавьте все файлы с помощью `git add .`, затем просмотрите изменения с помощью `git diff`. Например:
+
[source, shell]
....
% git add .
% git diff --staged
....
+
Убедитесь, что все необходимые файлы включены, затем зафиксируйте изменение в вашей локальной ветке и создайте патч с помощью `git format-patch`
+
[source, shell]
....
% git commit
% git format-patch origin/main
....
+
Патч, созданный с помощью `git format-patch`, будет содержать идентификатор автора и адреса электронной почты, что упрощает применение разработчиками (с помощью `git am`) и правильное указание авторства.
+
[IMPORTANT]
======
Чтобы упростить применение патча коммиттерами в их рабочей копии дерева документации, пожалуйста, сгенерируйте файл [.filename]#.diff# из корня вашего дерева документации.
======
+
В приведённом выше примере были внесены изменения в раздел *bsdinstall* Руководства.
+
. Отправьте патч или diff-файл с помощью веб-системы https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report]. При использовании веб-формы укажите в поле Summary _[patch] краткое описание проблемы_. Выберите Component `Documentation`. В поле Description введите краткое описание изменений и любые важные детали о них. Используйте кнопку btn:[Add an attachment], чтобы прикрепить патч или diff-файл. Наконец, нажмите кнопку btn:[Submit Bug], чтобы отправить ваш diff в систему отчётов об ошибках.
====

[[gnu-linux-installation-process]]
=== Процесс установки GNU/Linux

[.procedure]
====
. Установите эти пакеты в системах на основе apt, таких как Debian или Ubuntu. В других дистрибутивах GNU/Linux названия пакетов могут отличаться. В случае сомнений обратитесь к менеджеру пакетов вашего дистрибутива.
+
[source, shell]
....
# apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake
....
+
. Установите локальную рабочую копию документации из репозитория FreeBSD в [.filename]#~/doc# (см. crossref:working-copy[working-copy,Рабочая копия]).
+
[source, shell]
....
% git clone https://git.FreeBSD.org/doc.git ~/doc
....
+
. Отредактируйте файлы документации, которые требуют изменений. Если файлу нужны значительные изменения, обратитесь за советом в список рассылки.
+
Просмотрите вывод и отредактируйте файлы, чтобы исправить обнаруженные проблемы, затем снова запустите команду, чтобы найти оставшиеся проблемы. Повторяйте, пока все ошибки не будут устранены.
+
. Всегда собирайте и тестируйте изменения перед их отправкой. Запуск `bmake` в подкаталогах `documentation` или `website` сгенерирует документацию в формате HTML.
+
[source, shell]
....
% bmake run LOCALBASE=/usr
....
+
. Добавьте все файлы с помощью `git add .`, затем просмотрите изменения с помощью `git diff`. Например:
+
[source, shell]
....
% git add .
% git diff --staged
....
+
Убедитесь, что все необходимые файлы включены, затем зафиксируйте изменение в вашей локальной ветке и создайте патч с помощью `git format-patch`
+
[source, shell]
....
% git commit
% git format-patch origin/main
....
+
Патч, созданный с помощью `git format-patch`, будет содержать идентификатор автора и адреса электронной почты, что упрощает применение разработчиками (с помощью `git am`) и правильное указание авторства.
+
[IMPORTANT]
======
Чтобы упростить применение патча коммиттерами в их рабочей копии дерева документации, пожалуйста, сгенерируйте файл [.filename]#.diff# из корня вашего дерева документации.
======
+
. Отправьте патч или diff-файл с помощью веб-системы https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report]. При использовании веб-формы укажите в поле _Summary_ краткое описание проблемы. Выберите компонент `Documentation`. В поле _Description_ введите краткое описание проблемы из поля _Summary_ и добавьте _patch_ в поле _Keywords_. Используйте кнопку btn:[Add an attachment], чтобы прикрепить патч или diff-файл. Наконец, нажмите кнопку btn:[Submit Bug], чтобы отправить ваш diff в систему отчётов об ошибках.
====

[[mac-os-installation-process]]
=== Процесс установки macOS(R)

[.procedure]
====

. Установите эти пакеты с помощью link:https://brew.sh/[Homebrew] и link:https://rubygems.org/[RubyGem].
+
[source, shell]
....
$ brew install hugo ruby git bmake
....
+
. Добавьте Ruby в Path.
+
[source, shell]
....
$ echo 'export PATH="$(brew --prefix ruby)/bin:$PATH"' >> ~/.zshrc
$ echo 'export PATH="$(brew --prefix hugo)/bin:$PATH"' >> ~/.zshrc
$ echo 'export GEM_PATH="$(gem environment gemdir)"' >> ~/.zshrc
$ echo 'export PATH="${GEM_PATH}/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc
....
. Установите пакет rouge с помощью RubyGem.
+
[source, shell]
....
$ sudo gem install rouge asciidoctor asciidoctor-pdf asciidoctor-epub3
....
+
. Установите локальную рабочую копию документации из репозитория FreeBSD в [.filename]#~/doc# (см. crossref:working-copy[working-copy,Рабочая копия]).
+
[source, shell]
....
$ git clone https://git.FreeBSD.org/doc.git ~/doc
....
+
. Отредактируйте файлы документации, которые требуют изменений. Если файлу нужны значительные изменения, обратитесь за советом в список рассылки.
+
Просмотрите вывод и отредактируйте файлы, чтобы исправить обнаруженные проблемы, затем снова запустите команду, чтобы найти оставшиеся проблемы. Повторяйте, пока все ошибки не будут устранены.
+
. Всегда собирайте и тестируйте изменения перед их отправкой. Запуск `bmake` в подкаталогах `documentation` или `website` сгенерирует документацию в формате HTML.
+
[source, shell]
....
$ bmake run USE_RUBYGEMS=YES RUBY_CMD="$(brew --prefix ruby)/bin/ruby" HUGO_CMD="$(brew --prefix hugo)/bin/hugo"
....
. Добавьте все файлы с помощью `git add .`, затем просмотрите изменения с помощью `git diff`. Например:
+
[source, shell]
....
% git add .
% git diff --staged
....
+
Убедитесь, что все необходимые файлы включены, затем зафиксируйте изменение в вашей локальной ветке и создайте патч с помощью `git format-patch`
+
[source, shell]
....
% git commit
% git format-patch origin/main
....
+
Патч, созданный с помощью `git format-patch`, будет содержать идентификатор автора и адреса электронной почты, что упрощает применение разработчиками (с помощью `git am`) и правильное указание авторства.
+
[IMPORTANT]
======
Чтобы упростить применение патча коммиттерами в их рабочей копии дерева документации, пожалуйста, сгенерируйте файл [.filename]#.diff# из корня вашего дерева документации.
======
+
. Отправьте патч или diff-файл с помощью веб-системы https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report]. При использовании веб-формы укажите в поле _Summary_ краткое описание проблемы. Выберите компонент `Documentation`. В поле _Description_ введите краткое описание проблемы из поля _Summary_ и добавьте _patch_ в поле _Keywords_. Используйте кнопку btn:[Add an attachment], чтобы прикрепить патч или diff-файл. Наконец, нажмите кнопку btn:[Submit Bug], чтобы отправить ваш diff в систему отчётов об ошибках.
====

[[overview-doc]]
== Набор документации FreeBSD

FDP отвечает за четыре категории документации FreeBSD.

* _Руководство_: Руководство представляет собой всеобъемлющий онлайн-ресурс и справочник для пользователей FreeBSD.
* _FAQ_: В разделе Часто задаваемых вопросов (FAQ) используется формат коротких вопросов и ответов для решения вопросов, часто задаваемых в различных почтовых рассылках и форумах, посвящённых FreeBSD. Такой формат не подразумевает длинных и развёрнутых ответов.
* _Справочник_: Страницы Справочника (man-страницы) системы на английском языке обычно не создаются FDP, так как они являются частью базовой системы. Однако FDP может перефразировать части существующих руководств, чтобы сделать их понятнее или исправить неточности.
* _Веб-сайт_: Это основное представительство FreeBSD в интернете, доступное по адресу https://www.freebsd.org/[https://www.FreeBSD.org/] и на множестве зеркал по всему миру. Веб-сайт обычно становится первым знакомством нового пользователя с FreeBSD.

Команды переводчиков отвечают за перевод Руководства и веб-сайта на разные языки. На данный момент руководства (man-страницы) не переводятся.

Исходные тексты документации для веб-сайта FreeBSD, Handbook и FAQ доступны в репозитории документации по адресу `https://cgit.freebsd.org/doc/`.

Исходный код страниц справочника доступен в отдельном репозитории, расположенном по адресу `https://cgit.freebsd.org/src/`.

Документация сообщений о фиксациях доступна с помощью `git log`. Сообщения о фиксациях также архивируются по ссылке link:{dev-commits-doc-all}.

Веб-интерфейсы для обоих репозиториев доступны по адресам https://cgit.freebsd.org/doc/[] и https://cgit.freebsd.org/src/[].

Большое количество авторов участвовало в написании руководств или инструкций по FreeBSD. Некоторые из этих документов хранятся в рамках файлов FDP. В других случаях авторы предпочли опубликовать документацию отдельно. FDP стремится предоставить ссылки на как можно большее количество такой внешней документации.