[Bug 270481] intro(9) needs an update/rewrite

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=270481

            Bug ID: 270481
           Summary: intro(9) needs an update/rewrite
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: New
          Severity: Affects Only Me
          Priority: ---
         Component: Manual Pages
          Assignee: mhorne@freebsd.org
          Reporter: mhorne@freebsd.org
                CC: arch@FreeBSD.org, doc@FreeBSD.org
            Blocks: 248562

The intro(9) man page is outdated, with a last modified date of 1995(!). The
page contains a few general programming recommendations and a link to style(9).
Beyond this it fails to provide any real introduction to this section of
documentation.

While imperfect, section 9 is the most comprehensive set of documentation for
the FreeBSD kernel source code that exists. This man page has the potential to
be a useful landing page for navigating and discovering this resource.

A complete rewrite of this page is in order, with the following
goals/principles:
 - Provide more detailed high-level introduction to this documentation set;
describe purpose, authors & audience, and expectations regarding coverage,
level-of-detail, and accuracy
 - Include cross-references to as many section 9 pages as reasonable. This
improves their discoverability
 - Group links by subsystem/domain. NetBSD's intro(9) page is a good example of
this [1]

I have begun this rewrite, so this PR is self-assigned and mainly for tracking
purposes. Feedback on what should be usefully included in the new page is
welcome.

[1]
https://man.freebsd.org/cgi/man.cgi?query=intro&apropos=0&sektion=9&manpath=NetBSD+9.3&arch=default&format=html


Referenced Bugs:

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=248562
[Bug 248562] [meta] intro man pages: review, revamp, update
-- 
You are receiving this mail because:
You are on the CC list for the bug.