diff options
Diffstat (limited to 'documentation/content/ru/books/fdp-primer/overview/_index.adoc')
| -rw-r--r-- | documentation/content/ru/books/fdp-primer/overview/_index.adoc | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/documentation/content/ru/books/fdp-primer/overview/_index.adoc b/documentation/content/ru/books/fdp-primer/overview/_index.adoc new file mode 100644 index 0000000000..040a5a239a --- /dev/null +++ b/documentation/content/ru/books/fdp-primer/overview/_index.adoc @@ -0,0 +1,321 @@ +--- +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 +.... ++ +. Отредактируйте файлы документации, которые требуют изменений. Если файлу нужны значительные изменения, обратитесь за советом в список рассылки. ++ +Просмотрите вывод и отредактируйте файл, чтобы исправить указанные проблемы, затем повторно запустите команду для поиска оставшихся проблем. Повторяйте, пока все ошибки не будут устранены. ++ +. *_Always_* build and review the changes before submitting them. Running `make` in the `documentation` or `website` subdirectories will generate the documentation in HTML format. ++ +[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 +.... +. Добавьте все файлы с помощью `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 стремится предоставить ссылки на как можно большее количество такой внешней документации. |