Re: Documentation requirement (was [Call For Votes] PHP::Fork)

Greg Beaver wrote: > I would like to suggest an amendment to the package and documentation rules. Big +1! However, at the meeting this spring, it seems to me that when we discussed unit tests, documentation, etc., it was sort of like PFC standards, not beyond the minimum that Xavier mentioned in his post (from the meeting summary). As it now stands, there will need to be a lot of grandfathering for existing packages where the proposed standards don't apply. Of course, documentation and unit tests are a Good Thing (TM). If we require full documentation, unit tests, etc., for package proposals, it reminds me of the Middle Ages, where the ministerial class created their social status and then cut off the rungs on the ladder so that it was impossible to join them. They became a closed class. I don't think that's what we want for pear. Of course we want quality and documentation, but at what price? > However, I feel strongly that pear's issue is in fact allowing stable > releases BEFORE they are documented. How can a release be stable if it > is possible to use experimental elements within the stable release > without realizing it? Documentation serves to clearly define the API > that should be used, and so is obviously a requirement for stability. > > Note that my views have changed recently from greater experience - I > think alpha releases should have in-code documentation completely > up-to-date, and beta releases should have a frozen API, allowing more > definitive, stable documentation. I think this helps define the states. Currently, there is a lot of confusion concerning what state to assign to a release. These new guidelines would clarify things and help the users to understand the real state of things. Thanks for the help with phpDocumentor... I think there should be a chapter in the Developer Guide on how to generate a documentation framework using this wonderful tool :-) Klaus