I was going batty today trying to figure out why documentation ,
recommendations, and changelogs were conflicting when migrating an old
Pylons project.
Then I finally realized the problem - and noticed a large number of
people on StackOverflow were suffering from the same issue:
- The "Pylons Book" was/is often quoted and recommended for it's
thoroughness
- The "Pylons Book" is written for the Framework of 0.9.7
- The "Pylons Framework" is at 1.0.1
- The "Pylons Book" online is versioned, there was a 1.0 and it was
updated to a 1.1. It follows this URL Pattern - http://pylonsbook.com/en/1.1/ and has this on the top of every page "Pylons Book v1.1
documentation" The book is still written for the "Framework 0.9.7"
release though -- not the "Framework 1.0" changes.
It finally hit me that people were referencing the 1.1 documentation ,
assuming it was for the 1.1 framework release. But there is no 1.1
framework release -- just 1.0.1. People weren't misquoting the
framework release number - they were trying to use the 1.1 book ,
which covers 0.9.7 , on the 1.0.1 release - and total confusion
occurred.
Anyways, I think the moral of this story is that Pyramid shouldn't do
this. I don't know how , but any docs ( official or 3rd party )
shouldn't go off into a versioning system that is confusingly similar
to Pylons.
Pyramid has the advantage that its official docs are already the length and
quality of a book, and I think an earlier version of it (the BFG manual)
was even published. Now it's essentially a print-it-yourself book.
The Pylons Book is a product of its time. Maybe we should just release
Pylons 1.2 unchanged to eliminate confusion. The Pylons Book *is* thorough
and well-written, but it's dated and a couple chapters delved into esoteric
areas (the author's unique libraries).
My first recommendation to people would be to just use Pyramid, which is
"Pylons 2". If they want to use Pylons, they should read the online docs,
and be aware that some gaps have appeared. (Some links to third-party
documentation are dead, and "go-pylons.py was lost and no longer works so
you'll have to install a virtualenv and Pylons manually.) If they want to
follow the Pylons Book they need to check the online docs for the
differences between Pylons 1 and 0.9.7.
On Tue, Nov 27, 2012 at 11:23 AM, Jonathan Vanasco <jonat...@findmeon.com>wrote:
> I was going batty today trying to figure out why documentation ,
> recommendations, and changelogs were conflicting when migrating an old
> Pylons project.
> Then I finally realized the problem - and noticed a large number of
> people on StackOverflow were suffering from the same issue:
> - The "Pylons Book" was/is often quoted and recommended for it's
> thoroughness
> - The "Pylons Book" is written for the Framework of 0.9.7
> - The "Pylons Framework" is at 1.0.1
> - The "Pylons Book" online is versioned, there was a 1.0 and it was
> updated to a 1.1. It follows this URL Pattern -
> http://pylonsbook.com/en/1.1/ > and has this on the top of every page "Pylons Book v1.1
> documentation" The book is still written for the "Framework 0.9.7"
> release though -- not the "Framework 1.0" changes.
> It finally hit me that people were referencing the 1.1 documentation ,
> assuming it was for the 1.1 framework release. But there is no 1.1
> framework release -- just 1.0.1. People weren't misquoting the
> framework release number - they were trying to use the 1.1 book ,
> which covers 0.9.7 , on the 1.0.1 release - and total confusion
> occurred.
> Anyways, I think the moral of this story is that Pyramid shouldn't do
> this. I don't know how , but any docs ( official or 3rd party )
> shouldn't go off into a versioning system that is confusingly similar
> to Pylons.
> --
> You received this message because you are subscribed to the Google Groups
> "pylons-discuss" group.
> To post to this group, send email to pylons-discuss@googlegroups.com.
> To unsubscribe from this group, send email to
> pylons-discuss+unsubscribe@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/pylons-discuss?hl=en.
On Wednesday, November 28, 2012 1:45:37 PM UTC-5, Mike Orr wrote:
> The Pylons Book is a product of its time. Maybe we should just release > Pylons 1.2 unchanged to eliminate confusion. The Pylons Book *is* thorough > and well-written, but it's dated and a couple chapters delved into esoteric > areas (the author's unique libraries).
Honestly, I think that might be a good idea...
But I think maybe a big warning on the official Pylons Docs /migrations guides. specifically these 2 pages:
just something like : "Please note that Pylons Framework is at version 1.0.1 , while the PylonsBook version 1.1 covers the PylonsFramework 0.9.7. Some documentation on the PylonsBook 1.1 is out of date and incompatible with the PylonsFramework 1.0.1."
> My first recommendation to people would be to just use Pyramid, which is > "Pylons 2". If they want to use Pylons, they should read the online docs, > and be aware that some gaps have appeared. (Some links to third-party > documentation are dead, and "go-pylons.py was lost and no longer works so > you'll have to install a virtualenv and Pylons manually.)
I agree with that, but the bulk of people I saw confused / having issues (including myself) were those who were migrating legacy apps to 1.0.1 for maintenance. The Book unfortunately has a lot of SEO. If you search for migration help on random issues, the book's out-of-date docs come up... and folks on StackOverflow are very good and pointing to the Out Of Date docs based on the Book's version number.
