Chapter 1. Overview

Welcome to the FreeBSD Documentation Project (FDP). Quality documentation is crucial to the success of FreeBSD, and we value your contributions very highly.

This document describes how the FDP is organized, how to write and submit documentation, and how to effectively use the available tools.

Everyone is welcome to contribute to the FDP. Willingness to contribute is the only membership requirement.

This primer shows how to:

Understand the role of documentation and its place in the ecosystem.
Identify which parts of FreeBSD are maintained by the FDP.
Install the required documentation tools and files.
Make changes to the documentation.
Submit changes back for review and inclusion in the FreeBSD documentation.

1.1. Documentation in the FreeBSD Ecosystem

All documents are for the benefit of their readers, not their writers or caretakers. They should adapt to the reader and not expect the reader to adapt to them.

Never blame the reader for:

being unable to make use of a document easily or at all
finding a document confusing
not understanding a document or how to apply it
not finding an explicit answer or successfully bridging gaps (or connecting dots) to reason their way to one

Instead, acknowledge that the document is:

inaccessible
confusing
hard to understand or apply
incomplete

Then, make the document:

more accessible
less confusing
clearer
more complete

Use the following methods:

apply accessibility best practices to correct the problem reported and any similar ones you find
rework or clarify the confusing structure or language
add relevant examples to the part that is hard to understand or apply
fill in the gaps or add the missing stepping stones

1.2. Quick Start

Some preparatory steps must be taken before editing the FreeBSD documentation. First, subscribe to the FreeBSD documentation project mailing list. Some team members also interact on the #bsddocs IRC channel on EFnet. These people can help with questions or problems involving the documentation.

1.2.1. FreeBSD installation process

Install these packages. The docproj meta-port installs all the applications required to do useful work with the FreeBSD documentation.
```
# pkg install docproj
```
Install a local working copy of the documentation from the FreeBSD repository in ~/doc (see The Working Copy).
```
% git clone https://git.FreeBSD.org/doc.git ~/doc
```
Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.
Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved.
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
```
To reduce compile time, only one language can be compiled:
```
% make DOC_LANG=en
```
The build output is stored in ~/doc/documentation/public/en/articles/ and ~/doc/documentation/public/en/books/.
Review the build output and ensure the edits are free from typos, layout problems, or errors. If any errors are found during the build process, edit the problematic files to fix any issues that show up, then run the build command again until all errors are resolved.
Add all the files with git add ., then review the diff with git diff. For example:
```
% git add .
% git diff --staged
```
Make sure that all required files are included, then commit the change to your local branch and generate a patch with git format-patch
```
% git commit
% git format-patch origin/main
```
Patch generated with git format-patch will include author identity and email addresses, making it easier for developers to apply (with git am) and give proper credit.
To make it easier for committers to apply the patch on their working copy of the documentation tree, please generate the .diff from the base of your documentation tree.
In the example above, changes have been made to the bsdinstall portion of the Handbook.
Submit the patch or diff file using the web-based Problem Report system. If using the web form, enter a Summary of [patch] short description of problem. Select the Component Documentation. In the Description field, enter a short description of the changes and any important details about them. Use the Add an attachment button to attach the patch or diff file. Finally, use the Submit Bug button to submit your diff to the problem report system.

1.2.2. GNU/Linux installation process

Install these packages in apt-based systems like Debian or Ubuntu. On other GNU/Linux distributions the package names may change. Consult your distribution’s package manager if in doubt.
```
# apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake
```
Install a local working copy of the documentation from the FreeBSD repository in ~/doc (see The Working Copy).
```
% git clone https://git.FreeBSD.org/doc.git ~/doc
```
Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.
Review the output and edit the files to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved.
Always build and test the changes before submitting them. Running bmake in the documentation or website subdirectories will generate the documentation in HTML format.
```
% bmake run LOCALBASE=/usr
```
Add all the files with git add ., then review the diff with git diff. For example:
```
% git add .
% git diff --staged
```
Make sure that all required files are included, then commit the change to your local branch and generate a patch with git format-patch
```
% git commit
% git format-patch origin/main
```
Patch generated with git format-patch will include author identity and email addresses, making it easier for developers to apply (with git am) and give proper credit.
To make it easier for committers to apply the patch on their working copy of the documentation tree, please generate the .diff from the base of your documentation tree.
Submit the patch or diff file using the web-based Problem Report system. If using the web form, enter a Summary of short description of problem. Select the Component Documentation. In the Description field, enter a short description of the problem in the Summary field and add patch to the Keywords field. Use the Add an attachment button to attach the patch or diff file. Finally, use the Submit Bug button to submit your diff to the problem report system.

1.2.3. macOS® installation process

Install these packages using Homebrew and RubyGem.
```
$ brew install hugo ruby git bmake
```

Add Ruby to the Path.

$ echo 'export GEM_PATH="$(gem environment gemdir)"' >> ~/.zshrc
$ echo 'export PATH="$(brew --prefix ruby)/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

Add git alias to Homebrew git since git format-patch from Apple-provided git won’t work with Phabricator.
```
$ echo 'alias git=/usr/local/bin/git' >> ~/.zshrc
$ source ~/.zshrc
```

Install the rouge package using RubyGem.

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

Install a local working copy of the documentation from the FreeBSD repository in ~/doc (see The Working Copy).
```
$ git clone https://git.FreeBSD.org/doc.git ~/doc
```
Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.
Review the output and edit the files to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved.
Always build and test the changes before submitting them. Running bmake in the documentation or website subdirectories will generate the documentation in HTML format.
```
$ bmake run USE_RUBYGEMS=YES RUBY_CMD=$(brew --prefix ruby)/bin/ruby
```
Add all the files with git add ., then review the diff with git diff. For example:
```
% git add .
% git diff --staged
```
Make sure that all required files are included, then commit the change to your local branch and generate a patch with git format-patch
```
% git commit
% git format-patch origin/main
```
Patch generated with git format-patch will include author identity and email addresses, making it easier for developers to apply (with git am) and give proper credit.
To make it easier for committers to apply the patch on their working copy of the documentation tree, please generate the .diff from the base of your documentation tree.
Submit the patch or diff file using the web-based Problem Report system. If using the web form, enter a Summary of short description of problem. Select the Component Documentation. In the Description field, enter a short description of the problem in the Summary field and add patch to the Keywords field. Use the Add an attachment button to attach the patch or diff file. Finally, use the Submit Bug button to submit your diff to the problem report system.

1.3. The FreeBSD Documentation Set

The FDP is responsible for four categories of FreeBSD documentation.

Handbook: The Handbook is the comprehensive online resource and reference for FreeBSD users.
FAQ: The FAQ uses a short question and answer format to address questions that are frequently asked on the various mailing lists and forums devoted to FreeBSD. This format does not permit long and comprehensive answers.
Manual pages: The English language system manual pages are usually not written by the FDP, as they are part of the base system. However, the FDP can reword parts of existing manual pages to make them clearer or to correct inaccuracies.
Web site: This is the main FreeBSD presence on the web, visible at https://www.FreeBSD.org/ and many mirrors around the world. The web site is typically a new user’s first exposure to FreeBSD.

Translation teams are responsible for translating the Handbook and web site into different languages. Manual pages are not translated at present.

Documentation source for the FreeBSD web site, Handbook, and FAQ is available in the documentation repository at https://cgit.freebsd.org/doc/.

Source for manual pages is available in a separate source repository located at https://cgit.freebsd.org/src/.

Documentation commit messages are visible with git log. Commit messages are also archived at Commit messages for all branches of the doc repository.

Web frontends to both of these repositories are available at https://cgit.freebsd.org/doc/ and https://cgit.freebsd.org/src/.

Many people have written tutorials or how-to articles about FreeBSD. Some are stored as part of the FDP files. In other cases, the author has decided to keep the documentation separate. The FDP endeavors to provide links to as much of this external documentation as possible.

Last modified on: March 9, 2024 by Danilo G. Baio

Home