Lessons from the Pylons Book

[Jonathan Vanasco]

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.

[timblack1]

Pyramid could consider doing what Kevin Dangoor said a while back--"If it's not documented, it doesn't exist!"

http://markmail.org/message/ep3hfpx7cnxy7g5d

Tim

[Chris McDonough]

On 11/27/2012 11:47 PM, timblack1 wrote:
> Pyramid could consider doing what Kevin Dangoor said a while back--"If it's not documented, it doesn't exist!"

Already true.

- C

[Mike Orr]

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.

--
You received this message because you are subscribed to the Google Groups "pylons-discuss" group.
To post to this group, send email to pylons-...@googlegroups.com.
To unsubscribe from this group, send email to pylons-discus...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pylons-discuss?hl=en.

--
Mike Orr <slugg...@gmail.com>

[Jonathan Vanasco]

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:

- http://docs.pylonsproject.org/en/latest/docs/pylons.html

- http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/upgrading.html

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.