On Feb 27, 2007, at 4:34 PM, primco wrote: > Ben, could you elaborate on this some more? I've found the docs on > turbogears and django to be really hard to follow because they are > version specific, but I understand why it must be done. The "best" doc > system depends on the perspective of the end user. Newbies want one > set of docs, older developers stuck on a specific legacy version may > need different docs. When you have a latest and greatest best > practices doc, do people looking at 9.1 docs not see that?
The current plan is to have the docs reflect the latest version, and should there be something that is different from the last release and the 'trunk', it will be in there with a note indicating it applies only to trunk. When a release is then pushed out, the 'trunk' notes will be removed, and the entire doc will be exported to a HTML tarball and PDF for use by those running old releases. This way the docs online always apply to the latest version (as you note, its not practical to backport docs). > In addition, there's the web of documentation for supporting projects. > Docs for dealing with session state will be fairly different depending > on what version of pylons / orm you're using. Do you intend to link > the supporting projects documentation as well? So in essence, if you > have pylons 9.4.1 docs tree do you state in your docs that this works > with sql alchemy 0.3.5 and link references to sql alchemy as > http://www.sqlalchemy.org/docs_03/ ? I actually want to fully include all the docs you need to get going with Pylons. This means there will be a copy (with minor changes) of most of the core Mako docs, and a basic intro to SQLAlchemy (going deep into that will link to their docs). As there is a significant amount of users running with Genshi, I plan on including the same core intro to Genshi (both Mako and Genshi chapters will likely only be a half dozen pages). The docs on other parts (Genshi, Mako, SQLAlchemy) will be approaching it from a slightly different perspective from the core docs for each of those projects, so I don't see them having too much duplication. ToscaWidgets might be a little larger, as there's the "how to use it in Pylons" section, while the rest of it is fairly general to anyone using ToscaWidgets. I might be coorporating with TurboGears folks to see how we can merge our doc efforts on portions used by both projects to reduce the maintenance. Cheers, Ben --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "pylons-discuss" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/pylons-discuss?hl=en -~----------~----~----~----~------~----~------~--~---
