Re: [Framework-Team] Re: Fwd: Including a Documentation section in each PLIP
On Sat, Nov 15, 2008 at 6:01 PM, Wichert Akkerman wrote: >> > I would much rather see the equivalent of the what-is-new-in-python-x.y >> > documents: a thorough explanation of every change, its rationale, and >> > the inpact that has on both existing and new code. That would then be a >> > very useful starting point for the documentation team to update/extend >> > other documentation. >> > Israel Saeta wrote: >> If the documentation has to wait for version releases it will always >> be behind code, which leads (among other causes) to the actual state >> of some areas of the plone.org documentation: outdated. Of course the >> documentation team has great responsibility here, but trying to keep >> code as important as code will help. Wichert Akkerman wrote: > You misunderstood my point. What I want to see is for each PLIP to have > the equivalent of a section of the what-is-new-in-python-x.y documents. > That does not require waiting for a release. Uh yes you're right I've misunderstood you, my apologies. Maybe I'm behaving in a bit too defensive way here, sorry. I would be ok with any text explaining the impact of the PLIP in the way we develop with, customize, or manage Plone. Links to existing documentation that would become obsolete could be optional. Some trivial examples: - http://plone.org/products/plone/roadmap/238 Inline editing will be disabled by default. Update User Manual http://is.gd/7El5 . - http://plone.org/products/plone/roadmap/223 Theming resources based on base_properties.props will become deprecated in favour of zrt resources. -- Israel ___ Framework-Team mailing list Framework-Team@lists.plone.org http://lists.plone.org/mailman/listinfo/framework-team
Re: [Framework-Team] Re: Fwd: Including a Documentation section in each PLIP
Previously Israel Saeta Pérez wrote: > On Sat, Nov 15, 2008 at 5:08 PM, Wichert Akkerman wrote: > > Previously Martin Aspeli wrote: > >> I do agree that documentation should be part of PLIPs. One simple thing > >> would be to just have a free-text on the PLIP that identifies the > >> documentation that is either required or extant for the PLIP, so that > >> people who look at the PLIP later can find a pointer to where there's > >> more documentation. > > > > I would much rather see the equivalent of the what-is-new-in-python-x.y > > documents: a thorough explanation of every change, its rationale, and > > the inpact that has on both existing and new code. That would then be a > > very useful starting point for the documentation team to update/extend > > other documentation. > > If the documentation has to wait for version releases it will always > be behind code, which leads (among other causes) to the actual state > of some areas of the plone.org documentation: outdated. Of course the > documentation team has great responsibility here, but trying to keep > code as important as code will help. You misunderstood my point. What I want to see is for each PLIP to have the equivalent of a section of the what-is-new-in-python-x.y documents. That does not require waiting for a release. Wichert. -- Wichert Akkerman <[EMAIL PROTECTED]>It is simple to make things. http://www.wiggy.net/ It is hard to make things simple. ___ Framework-Team mailing list Framework-Team@lists.plone.org http://lists.plone.org/mailman/listinfo/framework-team
Re: [Framework-Team] Re: Fwd: Including a Documentation section in each PLIP
On Sat, Nov 15, 2008 at 5:08 PM, Wichert Akkerman wrote: > Previously Martin Aspeli wrote: >> I do agree that documentation should be part of PLIPs. One simple thing >> would be to just have a free-text on the PLIP that identifies the >> documentation that is either required or extant for the PLIP, so that >> people who look at the PLIP later can find a pointer to where there's >> more documentation. > > I would much rather see the equivalent of the what-is-new-in-python-x.y > documents: a thorough explanation of every change, its rationale, and > the inpact that has on both existing and new code. That would then be a > very useful starting point for the documentation team to update/extend > other documentation. If the documentation has to wait for version releases it will always be behind code, which leads (among other causes) to the actual state of some areas of the plone.org documentation: outdated. Of course the documentation team has great responsibility here, but trying to keep code as important as code will help. IMO we should try to update at least the most general documentation (manuals and important tutorials) before each release. To avoid problems, we could start with 2 or 3 easy-to-document PLIPs and see if we can manage to get relevant docs updated timely. -- israel @plone-docs: read the whole thread at http://is.gd/7DTi . ___ Framework-Team mailing list Framework-Team@lists.plone.org http://lists.plone.org/mailman/listinfo/framework-team
Re: [Framework-Team] Re: Fwd: Including a Documentation section in each PLIP
Previously Martin Aspeli wrote: > I do agree that documentation should be part of PLIPs. One simple thing > would be to just have a free-text on the PLIP that identifies the > documentation that is either required or extant for the PLIP, so that > people who look at the PLIP later can find a pointer to where there's > more documentation. I would much rather see the equivalent of the what-is-new-in-python-x.y documents: a thorough explanation of every change, its rationale, and the inpact that has on both existing and new code. That would then be a very useful starting point for the documentation team to update/extend other documentation. Wichert. -- Wichert Akkerman <[EMAIL PROTECTED]>It is simple to make things. http://www.wiggy.net/ It is hard to make things simple. ___ Framework-Team mailing list Framework-Team@lists.plone.org http://lists.plone.org/mailman/listinfo/framework-team
Re: [Framework-Team] Re: Fwd: Including a Documentation section in each PLIP
On Sat, Nov 15, 2008 at 2:15 PM, Martin Aspeli wrote: > I am not convinced that the Documentation Team at this point has enough > structure (both in terms of the actual corpus of documentation, and the team > itself) to facilitate this kind of process. There's been some very > encouraging movements on the doc list in the last few weeks, but like > Raphael, I'd be worried about this clogging up a process that's already > stretching the current team. > > I do agree that documentation should be part of PLIPs. One simple thing > would be to just have a free-text on the PLIP that identifies the > documentation that is either required or extant for the PLIP, so that people > who look at the PLIP later can find a pointer to where there's more > documentation. > > However, I think it's too much to ask at this point that the framework team > or PLIP authors go through all existing documentation looking for things > that may be outdated. We're likely moving towards splitting documentation into official and community parts, with the official one involving a continuous review process to ensure it's up to date and reliable. I agree with you: neither the PLIP submitter or the Framework Team can browse through *all* existing docs looking for obsolete practices, but we should try to document each new feature or change in at least one "authoritative" document, i.e. theming, archetypes or GS manuals. A documentation section with a few lines in each PLIP identifying changes in development, administering, customization or UI, maybe linking a example document that must be updated should be enough. Is this simple enough to start without clogging up the PLIP submit and review process? I hope so. -- Israel ___ Framework-Team mailing list Framework-Team@lists.plone.org http://lists.plone.org/mailman/listinfo/framework-team
[Framework-Team] Re: Fwd: Including a Documentation section in each PLIP
Israel Saeta Pérez wrote: I don't mind who actually identifies documentation that would need to be updated, if the PLIP submitter or the Framework Team, but I'm convinced every new feature or change should be reflected into the existing documentation, which is IMO as important as code and features. If we don't document new features as we introduce them, we will end up with obsolete documentation, as is already happening. If we don't like raising the bar for submitting PLIPs, at least we should commit to (really) introduce documentation in the release checklist: http://plone.org/development/teams/framework/process/ I'm sure the Documentation Team will be happy to collaborate with the Framework Team to get things done timely. I am not convinced that the Documentation Team at this point has enough structure (both in terms of the actual corpus of documentation, and the team itself) to facilitate this kind of process. There's been some very encouraging movements on the doc list in the last few weeks, but like Raphael, I'd be worried about this clogging up a process that's already stretching the current team. I do agree that documentation should be part of PLIPs. One simple thing would be to just have a free-text on the PLIP that identifies the documentation that is either required or extant for the PLIP, so that people who look at the PLIP later can find a pointer to where there's more documentation. However, I think it's too much to ask at this point that the framework team or PLIP authors go through all existing documentation looking for things that may be outdated. Martin -- Author of `Professional Plone Development`, a book for developers who want to work with Plone. See http://martinaspeli.net/plone-book ___ Framework-Team mailing list Framework-Team@lists.plone.org http://lists.plone.org/mailman/listinfo/framework-team
Re: [Framework-Team] Fwd: Including a Documentation section in each PLIP
On Sat, Nov 15, 2008 at 4:57 AM, Raphael Ritz wrote: > Steve McMahon wrote: >> >> Hi Framework Team, >> > > Hi Steve and Israel, > > first of all thanks for bringing this up. > > Just one personal comment from my side: > > I think I do understand where this is coming from > and I really appreciate the intention. > But (there's almost always a but in real life > isn't it ...) lets try to be realistic: > > First, I'm much in favor of having the PLIP process > as easy as possible. First and foremost we should > be interested in ideas and implementations I think. > Everything else should follow from there. > > Second, it is my understanding that much of what's > proposed here should be the responsibility of the > framework team. At least I usually try to point out > where I think documentation (be it new or an update) > is needed on an individual basis. > > Don't get me wrong but I seriously think that raising > the bar for submitting PLIPs or accepting them beyond > of what we require today already might be problematic. > > Others may disagree, of course, but I only want to stress > the fact that it is one thing to formulate wishful thinking > and another to value openness and accessibility. Dear Raphael, Thanks for your cents! :-) I don't mind who actually identifies documentation that would need to be updated, if the PLIP submitter or the Framework Team, but I'm convinced every new feature or change should be reflected into the existing documentation, which is IMO as important as code and features. If we don't document new features as we introduce them, we will end up with obsolete documentation, as is already happening. If we don't like raising the bar for submitting PLIPs, at least we should commit to (really) introduce documentation in the release checklist: http://plone.org/development/teams/framework/process/ I'm sure the Documentation Team will be happy to collaborate with the Framework Team to get things done timely. -- Israel ___ Framework-Team mailing list Framework-Team@lists.plone.org http://lists.plone.org/mailman/listinfo/framework-team
