> both regarding content and markup (including pf.conf(5) and > ifconfig(8)), and that is not a coincidence: The subject matter is > unusually difficult, the number of features to explain is unusually > large, the number of people qualified to judge the accuracy of the > manual pages and proposed changes is unusually small, and many of > them are unusually busy.
Let me try to provide some perspective why. Simple uses are easy to document (ie. "do this, here is an example, copy it. you don't need to understand). Complex usage cases eventually hit questions regarding order-of-evaluation. We made mostly correct decisions years ago, but people trying to use the code don't immediately come to the same conclusions since they are learning the field at the same time. These details should be documented, or someone must figure it out themsleves. But where? Describing both simple behaviours and complicated behaviours together is very difficult. In all fields. I'm also very wary of documentation changes in complicated areas, because most of the proposals are focusing on "me" cases, rather than trying to capture all the angles.
