Date: Wed, 26 Oct 2022 21:30:41 -0400 From: Allan Jude <allanjude@freebsd.org> To: freebsd-doc@freebsd.org Subject: Re: Documentation of /usr/src directory layout Message-ID: <718215e8-81cb-75e0-dcd5-9e41dd89ff11@freebsd.org> In-Reply-To: <1e1fce17-5953-9fc3-e1c4-59bbf5086e0c@freebsd.org> References: <b453ee35-e0ae-127c-cc22-1193d44c9bd4@freebsd.org> <CAPyFy2BXhWoPmGxQpjbqq=F7Zh2qjreqCBVSVZyS5AQdE95qeA@mail.gmail.com> <1e1fce17-5953-9fc3-e1c4-59bbf5086e0c@freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2022-10-26 14:41, Mitchell Horne wrote: > On 10/26/22 15:06, Ed Maste wrote: >> On Wed, 26 Oct 2022 at 12:07, Mitchell Horne <mhorne@freebsd.org> wrote: >>> >>> I propose that we reduce the maintenance overhead by keeping one of >>> these lists as the source of truth. README.md is the more natural option >>> here: being located at the root of the src tree it is more discoverable >>> (especially for those new to the src tree), and the raw markdown text is >>> much more human-readable than mdoc. Of course, the added benefit is that >>> README.md is presented front-and-center when browsing the git repository >>> on GitHub, GitLab, etc. See it on my fork [2]. >> >> Thanks Mitchell, overall I think this is a great idea. One question, >> is README.md the right place for this or should we add a >> CONTRIBUTING.md or similar? > > IMO, it is appropriate to keep this in README.md, if for no other reason > than the file is quite small -- 42 lines after my changes, including the > table. But I consider it analogous to having a map displayed at a park > entrance, or a table of contents at the start of a book. > I agree README.md is best, it is what tools like gitlab and github show by default, so again to Mitchell's point, it is the most discoverable location. -- Allan Jude
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?718215e8-81cb-75e0-dcd5-9e41dd89ff11>