Bug 273619

Summary:	Committer's guide: potential for confusion with the currently given paths
Product:	Documentation	Reporter:	Graham Perrin <grahamperrin>
Component:	Books & Articles	Assignee:	Sergio Carlavilla Delgado <carlavilla>
Status:	Closed Not Accepted
Severity:	Affects Some People	CC:	doc
Priority:	---
Version:	Latest
Hardware:	Any
OS:	Any
URL:	https://github.com/freebsd/freebsd-doc/blob/main/documentation/content/en/articles/committers-guide/_index.adoc#71-for-new-committers

Description Graham Perrin 2023-09-07 17:18:24 UTC

In <https://docs.freebsd.org/en/articles/committers-guide/#conventions> step 1, it's not immediately clear that doc/ means the doc tree. 

From step 5 and then step 9 it might be inferred that the first word in a path represents a tree, however (to the best of my recollection) this approach is not commonplace. 

In any case: inference is not ideal. Instead, be clear. 

<https://docs.freebsd.org/en/books/fdp-primer/book/#writing-style-be-clear>

Comment 1 Sergio Carlavilla Delgado freebsd_committer

2023-09-07 17:21:54 UTC

The first point[1] explains that src, doc and ports makes references to the repositories.


[1] https://docs.freebsd.org/en/articles/committers-guide/#admin

Comment 2 Graham Perrin 2023-09-07 17:29:27 UTC

This bug report was in response to a private email from someone. 

(In reply to Graham Perrin ◐ from comment #0)

> _immediately_ clear 

Section 7.1 step 1 is some way away from the separate page for section 1. The former had me confused for a while, recently. I'm not the only person.