Глава 1. Обзор

Этот перевод может быть устаревшим. Для того, чтобы помочь с переводом, пожалуйста, обратитесь к Сервер переводов FreeBSD.

Содержание

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

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

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

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

  • Понять роль документации и её место в экосистеме.

  • Определите, какие части FreeBSD поддерживаются FDP.

  • Установить необходимые инструменты и файлы документации.

  • Внести изменения в документацию.

  • Представить изменения для проверки и включения в документацию FreeBSD.

1.1. Документация в экосистеме FreeBSD

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

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

  • невозможность легко или вообще использовать документ

  • если документ показался ему непонятным

  • непонимание документа или того, как его применить

  • если он не нашел явный ответ или шаги, чтобы логически прийти к нему

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

  • недоступный

  • запутанный

  • трудно понимаемый или применимый

  • неполный

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

  • более доступный

  • менее запутанный

  • более ясный

  • более полный

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

  • Примените лучшие практики доступности, чтобы исправить выявленную проблему и любые подобные, которые обнаружите

  • переработайте или уточните запутанную структуру или язык

  • добавьте соответствующие примеры к части, которая трудна для понимания или применения

  • заполните пробелы или добавьте недостающие промежуточные этапы

1.2. Быстрый старт

Некоторые подготовительные шаги необходимо выполнить перед редактированием документации FreeBSD. Сначала подпишитесь на рассылку Список рассылки Проекта Документации FreeBSD. Некоторые участники команды также общаются в IRC-канале #bsddocs на EFnet. Эти люди могут помочь с вопросами или проблемами, связанными с документацией.

1.2.1. Процесс установки FreeBSD

  1. Установите эти пакеты. Мета-порт docproj устанавливает все приложения, необходимые для работы с документацией FreeBSD.

    # pkg install docproj

  2. Установите локальную рабочую копию документации из репозитория FreeBSD в ~/doc (см. Рабочая копия).

    % git clone https://git.FreeBSD.org/doc.git ~/doc

  3. Отредактируйте файлы документации, которые требуют изменений. Если файлу нужны значительные изменения, обратитесь за советом в список рассылки.

    Просмотрите вывод и отредактируйте файл, чтобы исправить указанные проблемы, затем повторно запустите команду для поиска оставшихся проблем. Повторяйте, пока все ошибки не будут устранены.

  4. Always build and review the changes before submitting them. Running make in the documentation or website subdirectories will generate the documentation in HTML format.

    % make

    Для сокращения времени компиляции может быть скомпилирован только один язык:

    % make DOC_LANG=en

    Результаты сборки сохраняются в ~/doc/documentation/public/en/articles/ и ~/doc/documentation/public/en/books/.

  5. Просмотрите вывод сборки и убедитесь, что правки не содержат опечаток, проблем с версткой или ошибок. Если в процессе сборки обнаружены ошибки, отредактируйте проблемные файлы, чтобы исправить все возникшие проблемы, затем снова запустите команду сборки, пока все ошибки не будут устранены.

  6. Добавьте все файлы с помощью git add ., затем просмотрите изменения с помощью git diff. Например:

    % git add .
% git diff --staged

    Убедитесь, что все необходимые файлы включены, затем зафиксируйте изменение в вашей локальной ветке и создайте патч с помощью git format-patch

    % git commit
% git format-patch origin/main

    Патч, созданный с помощью git format-patch, будет содержать идентификатор автора и адреса электронной почты, что упрощает применение разработчиками (с помощью git am) и правильное указание авторства.

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

    В приведенном выше примере были внесены изменения в раздел bsdinstall Руководства.

  7. Отправьте патч или diff-файл с помощью веб-системы Problem Report. При использовании веб-формы укажите в поле Summary [patch] краткое описание проблемы. Выберите Component Documentation. В поле Description введите краткое описание изменений и любые важные детали о них. Используйте кнопку Add an attachment, чтобы прикрепить патч или diff-файл. Наконец, нажмите кнопку Submit Bug, чтобы отправить ваш diff в систему отчетов об ошибках.

1.2.2. Процесс установки GNU/Linux

  1. Установите эти пакеты в системах на основе apt, таких как Debian или Ubuntu. В других дистрибутивах GNU/Linux названия пакетов могут отличаться. В случае сомнений обратитесь к менеджеру пакетов вашего дистрибутива.

    # apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake

  2. Установите локальную рабочую копию документации из репозитория FreeBSD в ~/doc (см. Рабочая копия).

    % git clone https://git.FreeBSD.org/doc.git ~/doc

  3. Отредактируйте файлы документации, которые требуют изменений. Если файлу нужны значительные изменения, обратитесь за советом в список рассылки.

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

  4. Всегда собирайте и тестируйте изменения перед их отправкой. Запуск bmake в подкаталогах documentation или website сгенерирует документацию в формате HTML.

    % bmake run LOCALBASE=/usr

  5. Добавьте все файлы с помощью git add ., затем просмотрите изменения с помощью git diff. Например:

    % git add .
% git diff --staged

    Убедитесь, что все необходимые файлы включены, затем зафиксируйте изменение в вашей локальной ветке и создайте патч с помощью git format-patch

    % git commit
% git format-patch origin/main

    Патч, созданный с помощью git format-patch, будет содержать идентификатор автора и адреса электронной почты, что упрощает применение разработчиками (с помощью git am) и правильное указание авторства.

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

  6. Отправьте патч или diff-файл с помощью веб-системы Problem Report. При использовании веб-формы укажите в поле Summary краткое описание проблемы. Выберите компонент Documentation. В поле Description введите краткое описание проблемы из поля Summary и добавьте patch в поле Keywords. Используйте кнопку Add an attachment, чтобы прикрепить патч или diff-файл. Наконец, нажмите кнопку Submit Bug, чтобы отправить ваш diff в систему отчетов об ошибках.

1.2.3. Процесс установки macOS®

  1. Установите эти пакеты с помощью Homebrew и RubyGem.

    $ brew install hugo ruby git bmake

  2. Добавьте Ruby в Path.

    $ 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

  3. Установите пакет rouge с помощью RubyGem.

    $ sudo gem install rouge asciidoctor asciidoctor-pdf asciidoctor-epub3

  4. Установите локальную рабочую копию документации из репозитория FreeBSD в ~/doc (см. Рабочая копия).

    $ git clone https://git.FreeBSD.org/doc.git ~/doc

  5. Отредактируйте файлы документации, которые требуют изменений. Если файлу нужны значительные изменения, обратитесь за советом в список рассылки.

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

  6. Всегда собирайте и тестируйте изменения перед их отправкой. Запуск bmake в подкаталогах documentation или website сгенерирует документацию в формате HTML.

    $ bmake run USE_RUBYGEMS=YES RUBY_CMD=$(brew --prefix ruby)/bin/ruby

  7. Добавьте все файлы с помощью git add ., затем просмотрите изменения с помощью git diff. Например:

    % git add .
% git diff --staged

    Убедитесь, что все необходимые файлы включены, затем зафиксируйте изменение в вашей локальной ветке и создайте патч с помощью git format-patch

    % git commit
% git format-patch origin/main

    Патч, созданный с помощью git format-patch, будет содержать идентификатор автора и адреса электронной почты, что упрощает применение разработчиками (с помощью git am) и правильное указание авторства.

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

  8. Отправьте патч или diff-файл с помощью веб-системы Problem Report. При использовании веб-формы укажите в поле Summary краткое описание проблемы. Выберите компонент Documentation. В поле Description введите краткое описание проблемы из поля Summary и добавьте patch в поле Keywords. Используйте кнопку Add an attachment, чтобы прикрепить патч или diff-файл. Наконец, нажмите кнопку Submit Bug, чтобы отправить ваш diff в систему отчетов об ошибках.

1.3. Набор документации FreeBSD

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

  • Руководство: Руководство представляет собой всеобъемлющий онлайн-ресурс и справочник для пользователей FreeBSD.

  • FAQ: В разделе Часто задаваемых вопросов (FAQ) используется формат коротких вопросов и ответов для решения вопросов, часто задаваемых в различных почтовых рассылках и форумах, посвящённых FreeBSD. Такой формат не подразумевает длинных и развёрнутых ответов.

  • Справочник: Страницы Справочника (man-страницы) системы на английском языке обычно не создаются FDP, так как они являются частью базовой системы. Однако FDP может перефразировать части существующих руководств, чтобы сделать их понятнее или исправить неточности.

  • Веб-сайт: Это основное представительство FreeBSD в интернете, доступное по адресу 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 стремится предоставить ссылки на как можно большее количество такой внешней документации.

Изменено: 20 сентября 2025 г. by Vladlen Popolitov

Главная