5 ms·

As the author, I'm interested in improving the Pyramid docs. Can you elaborate on your issues with them? Did you notice the tutorials at http://docs.pylonshq.

by chrism 16y ago

As the author, I'm interested in improving the Pyramid docs. Can you elaborate on your issues with them? Did you notice the tutorials at http://docs.pylonshq.com/pyramid/dev/index.html#tutorials http://docs.pylonshq.com/pyramid/dev/index.html#tutorials (lots of people seem to miss them).

stdbrouw 16y ago
Hi Chris. Off the top of my head, from when I was working on a Pyramid app ~ a month ago: - No clear visual distinction between links to glossary terms and links to further documentation. I like the glossary, but always ended up there without wanting to. - I did find the tutorials, no issue there. (Only that the paster templates are a bit awkwardly named, but that's not a doc issue.) - Especially the former BFG stuff, I'm thinking specifically about traversal, is explained in a way that probably makes a ton of sense to Zopeheads, but, at the time anyway, read more like a PhD thesis than like documentation. - Again not strictly a documentation issue, but the fact that you can configure and use Pyramid in a ton of different ways means there's no straight path from getting started to actually getting something up and running, even with the tutorials. Not being opinionated about anything simply makes it very difficult to write good, forceful docs.
- chrism 16y ago
  "No clear visual distinction between links to glossary terms": yep, fixed a while back. Glossary terms are now green, other links are blue. Traversal explaining: we're working on it (really). The docs have been rearranged and massaged a good bit, and they're being futher (professionally) edited now. Flexibility: the best I can do about that without betraying the goals of the project is http://docs.pylonshq.com/pyramid/dev/designdefense.html#pyramid-provides-more-than-one-way-to-do-it http://docs.pylonshq.com/pyramid/dev/designdefense.html#pyra... . I'm also working on a cookbook here: https://github.com/Pylons/pyramid_cookbook https://github.com/Pylons/pyramid_cookbook which should provide the tl;dr'ers with a way to perform common tasks without needing to read didactic explanations.
  - stdbrouw 16y ago
    I still have to finish up my Pyramid app next month (work project at a Plone shop), so it's good to know that the docs are getting better. Kudos!
- markramm 16y ago
  We are definitely fixing the traversal docs, and they are already much improved over two weeks ago ;) The responsiveness of Chris and Ben to actually fixing this kind of thing is amazing, and one of the major reasons we thought teaming up with them would be a good idea.

by chrism 16y ago

stdbrouw 16y ago

Hi Chris. Off the top of my head, from when I was working on a Pyramid app ~ a month ago: - No clear visual distinction between links to glossary terms and links to further documentation. I like the glossary, but always ended up there without wanting to. - I did find the tutorials, no issue there. (Only that the paster templates are a bit awkwardly named, but that's not a doc issue.) - Especially the former BFG stuff, I'm thinking specifically about traversal, is explained in a way that probably makes a ton of sense to Zopeheads, but, at the time anyway, read more like a PhD thesis than like documentation. - Again not strictly a documentation issue, but the fact that you can configure and use Pyramid in a ton of different ways means there's no straight path from getting started to actually getting something up and running, even with the tutorials. Not being opinionated about anything simply makes it very difficult to write good, forceful docs.

chrism 16y ago
"No clear visual distinction between links to glossary terms": yep, fixed a while back. Glossary terms are now green, other links are blue. Traversal explaining: we're working on it (really). The docs have been rearranged and massaged a good bit, and they're being futher (professionally) edited now. Flexibility: the best I can do about that without betraying the goals of the project is http://docs.pylonshq.com/pyramid/dev/designdefense.html#pyramid-provides-more-than-one-way-to-do-it http://docs.pylonshq.com/pyramid/dev/designdefense.html#pyra... . I'm also working on a cookbook here: https://github.com/Pylons/pyramid_cookbook https://github.com/Pylons/pyramid_cookbook which should provide the tl;dr'ers with a way to perform common tasks without needing to read didactic explanations.
- stdbrouw 16y ago
  I still have to finish up my Pyramid app next month (work project at a Plone shop), so it's good to know that the docs are getting better. Kudos!
markramm 16y ago
We are definitely fixing the traversal docs, and they are already much improved over two weeks ago ;) The responsiveness of Chris and Ben to actually fixing this kind of thing is amazing, and one of the major reasons we thought teaming up with them would be a good idea.