I was recently asked on IRC about what I considered were the drawbacks to the current Porter's Handbook. Well, I'm glad you asked me that

Global changes

• It combines what I think of as a User's Guide (or Introduction) and a Reference Book. It should only be the latter. The former needs to be its own article because it is of interest to more than just developers.

• The information about “keeping up” needs to be its own separate article, or moved to the Handbook. It is not of developer-only interest. In particular, it needs to grow information about how to set up cvsup in both its modes; how and why to set up portaudit; how to use portmanager; and any number of other similar topics that “expert port users” know but people new to FreeBSD have no clue about.

• All of the information about “policies” needs to be moved to the portmgr policies page so there is no duplication (and thus, chance for drift).

• We (portmgr) have to make it clear what things are Recommendations and what things are Requirements. e.g. exactly what is portmgr willing to enforce with, if necessary, backouts and commit bit suspensions. This way everyone who chafes under any “new policy” can figure out where they stand (whether it is one or the other).

• Many things are discussed in detail even before all the general concepts have been introduced. Things need to be reordered.

• About half of the “accepted practices” are missing.

• About half of the meta-variables are not yet documented.

• Some of the things in “Do's And Don'ts” appear much too late. Some of the other things aren't even appropriate for that section.

• Some of the text (list of Makevars) needs to come out of where it currently is and be in Appendices. References to the Appendices should then take their place. (Or maybe not.)

There are surely more.

Missing content

• USE_MYSQL, USE_PGSQL, USE_SQLITE etc are completely missing
• Fill up emacs section. Responsible person: AndreySlusar
• MOVED file has not mentioned anywhere
• New DEPENDS style with <,>,⇐,>= is not described

Folks are encouraged to provide patches as docs PRs.