https://issues.apache.org/SpamAssassin/show_bug.cgi?id=6740
--- Comment #5 from Kevin A. McGrail <[email protected]> 2012-01-03 16:06:48 UTC --- (In reply to comment #4) > Sigh, > > Documention is also important and having a good structure, hopefully more > standardized than confusing, helps everybody. I already run too many projects > of my own, so I'm unfortunately unable to contribute to anything related to > what you mentioned. > > What are used daily, are the manual pages. To be able find ("find", more than > "read and understand") information essential. > > The OPTIONS section, or any reference section (FILES, ENVIRONMENT), is much > more easier to treat when thing flow natural, alphabetical order. You have > predictability with search "back" and "forward". > > If anything needs to be related together, the best place, which I find useful > is "EXAMPLES". This is the first section that has the opportunity to show how > to use the utility in typical use cases. The "grouping" is much more effective > here and in reference-like OPTIONS section. > > And, if you looked at the patch, it also fixes missing or incorrect entries > which become evident during the harmonization. > > I'm prepared to write the initial EXAMPLES if that is what is needed to > persuade you that this is important step up in quality of the documentation > (IMHO). I agree. As an engineer, I play with things like examples and then read the documentation. If there are no EXAMPLES, I would happily add those if you want to submit them. However, the idea of reordering the options is time consuming with little gain and controversial if others on the PMC would support the change. I hate to waste people's time and feel bad you made these edits. I know you meant well. -- Configure bugmail: https://issues.apache.org/SpamAssassin/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the assignee for the bug.
