I do not have definitive answers. I will try review the book annually, usually in August. When I do this is the process: - I diff the online book with the printed book - I go over the logs to see which features are undocumented and need documenting - If I add documentation then it becomes a stable backward compatible feature (*) - I publish the new book
(*) it is a bit of a chicken and egg issue. It is stable if I feel it is useful and general enough based on my expectation, actual usage and discussions on the mailing lists. There is no formula for making this decision. If you feel something needs improvement you can always raise up the issue on the mailing list and that will prevent the feature to become stable. Massimo On Apr 27, 8:09 am, villas <[email protected]> wrote: > It is tricky for book editors to write new sections for the book for > various reasons: > e.g. > > - Editors do not usually know the full background and intent of new > features. > > - As new features are always introduced as unstable, it is too early > to document them. Typically there are relevant group postings > (sometimes split between the two groups), but these are easily > fragmented and lost. > > - Once features are documented in the book, Massimo tends to consider > them eligible for backward-compatibility. Therefore that decision is > very important and is beyond the scope of an editor and can only be > made by a core developer. > > We do need to agree a new work-flow. Here are a couple of questions > to move the discussion forward a little: > > 1. Does Massimo intend to review, overhaul and re-issue a new edition > of the book annually? > > 2. Perhaps we could add sections to the book (e.g. in a different > color) which are clearly identified as unstable/experimental? Or > perhaps, the wiki idea (by VP) is better for that? > > 3. Can Massimo introduce some way of informing when a feature is > considered stable and therefore ready for formal inclusion in the > book? > > Thanks, D
