RFD: suggested changes to "A project model for the FreeBSD Project"
Pau Amma
pauamma at gundo.com
Thu Oct 31 19:58:59 UTC 2019
I just finished reading through
https://www.freebsd.org/doc/en_US.ISO8859-1/books/dev-model/ for the first
time, and I believe it would be a better document with some or all of the
following changes, not all of which I have the required information to
specify completely:
- The text should use "they" instead of "he" or "he/she" pronouns
throughout. I believe this would be more in conformance with the spirit of
https://www.freebsd.org/internal/code-of-conduct.html and more respectful
of women and non-binary people, as well as less clunky IMO.
- The files listing maintainers for specific areas of the source code are
called "MAINTAINERS", not "MAINTAINER" (see 5.1.2 in
https://www.freebsd.org/doc/en_US.ISO8859-1/books/dev-model/sect-hats.html#general-hats).
- In section 5.1.3 (same URL as above), "As by" should be "As of".
- Figure 5.1 in
https://www.freebsd.org/doc/en_US.ISO8859-1/books/dev-model/official-hats.html
looks outdated and should have a better alt= or long description than just
its caption, and likewise for
https://www.freebsd.org/doc/en_US.ISO8859-1/books/dev-model/model-processes.html
(and for all other figures in the whole document).
-
https://www.freebsd.org/doc/en_US.ISO8859-1/books/dev-model/model-mailman.html
still refers to CVS instead of SVN.
- Caption of figure 8.1 in
https://www.freebsd.org/doc/en_US.ISO8859-1/books/dev-model/sub-projects.html
links to a no-longer-existent image, and is severely outdated. (2005 was
14 years ago.) See https://www.freshports.org/graphs2.php and
https://web.archive.org/web/20121223081637/http://www.freebsd.org/ports/growth/status.png
for more recent data. But better IMO (and easier to keep current) would be
a table.
-
https://www.freebsd.org/doc/en_US.ISO8859-1/books/dev-model/sub-project-documentation.html
should link to the FDP at
https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/.
Advice, suggestions, discussion, and comments all welcome.
More information about the freebsd-doc
mailing list