From owner-freebsd-doc@freebsd.org Thu Oct 31 19:58:59 2019 Return-Path: Delivered-To: freebsd-doc@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id D98BB164A02 for ; Thu, 31 Oct 2019 19:58:59 +0000 (UTC) (envelope-from pauamma@gundo.com) Received: from mail.gundo.com (gibson.gundo.com [75.145.166.65]) by mx1.freebsd.org (Postfix) with ESMTP id 473x3Q6yM5z3H01 for ; Thu, 31 Oct 2019 19:58:58 +0000 (UTC) (envelope-from pauamma@gundo.com) Received: from webmail.gundo.com (ibanez.gundo.com [75.145.166.66]) by mail.gundo.com (Postfix) with ESMTP id BA222520008 for ; Thu, 31 Oct 2019 14:58:57 -0500 (CDT) Received: from 176.142.0.50 (SquirrelMail authenticated user pauamma) by webmail.gundo.com with HTTP; Thu, 31 Oct 2019 19:58:57 -0000 Message-ID: Date: Thu, 31 Oct 2019 19:58:57 -0000 Subject: RFD: suggested changes to "A project model for the FreeBSD Project" From: "Pau Amma" To: freebsd-doc@freebsd.org User-Agent: SquirrelMail/1.4.22 MIME-Version: 1.0 Content-Type: text/plain;charset=iso-8859-1 Content-Transfer-Encoding: 8bit X-Priority: 3 (Normal) Importance: Normal X-Rspamd-Queue-Id: 473x3Q6yM5z3H01 X-Spamd-Bar: ---- Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=pass (mx1.freebsd.org: domain of pauamma@gundo.com designates 75.145.166.65 as permitted sender) smtp.mailfrom=pauamma@gundo.com X-Spamd-Result: default: False [-4.83 / 15.00]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-1.000,0]; FROM_HAS_DN(0.00)[]; R_SPF_ALLOW(-0.20)[+a]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[freebsd-doc@freebsd.org]; TO_DN_NONE(0.00)[]; RCPT_COUNT_ONE(0.00)[1]; NEURAL_HAM_LONG(-1.00)[-1.000,0]; RCVD_COUNT_THREE(0.00)[3]; DMARC_NA(0.00)[gundo.com]; RCVD_IN_DNSWL_MED(-0.20)[65.166.145.75.list.dnswl.org : 127.0.9.2]; HAS_X_PRIO_THREE(0.00)[3]; RCVD_NO_TLS_LAST(0.10)[]; FROM_EQ_ENVFROM(0.00)[]; R_DKIM_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:33491, ipnet:75.145.128.0/18, country:US]; IP_SCORE(-2.43)[ip: (-9.36), asn: 33491(-2.71), country: US(-0.05)] X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 31 Oct 2019 19:58:59 -0000 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.