1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
---
title: Chapter 1. Overview
prev: books/fdp-primer/preface
next: books/fdp-primer/tools
description: Overview about the FreeBSD Documentation Process
tags: ["overview", "FreeBSD Documentation Project", "quick start"]
---
[[overview]]
= 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::[]
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:
* 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.
[[overview-quick-start]]
== Quick Start
Some preparatory steps must be taken before editing the FreeBSD documentation.
First, subscribe to the {freebsd-doc}.
Some team members also interact on the `#bsddocs` IRC channel on http://www.efnet.org/[EFnet].
These people can help with questions or problems involving the documentation.
[.procedure]
====
. Install these packages. The `docproj` _meta-port_ installs all the applications required to do useful work with the FreeBSD documentation.
+
[source,shell]
....
# pkg install docproj python3
....
+
. Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]).
+
[source,shell]
....
% 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 test the changes before submitting them. Running `make` in the top-level directory of the documentation will generate that documentation in HTML format.
+
[source,shell]
....
% make
....
+
. When changes are complete and tested, generate a "diff file":
+
[source,shell]
....
% cd ~/doc
% git diff > bsdinstall.diff.txt
....
+
Give the diff file a descriptive name.
In the example above, changes have been made to the [.filename]#bsdinstall# portion of the Handbook.
. Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[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 btn:[Add an attachment] button to attach the diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system.
====
[[overview-doc]]
== 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/[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 link:{git-doc-all}.
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.
|
