13 messages in com.googlegroups.pylons-discussRe: ConceptsOfPylons and Pylons Docum...| From | Sent On | Attachments |
|---|---|---|
| John_Nowlan | 27 Feb 2007 10:27 | |
| Christoph Haas | 27 Feb 2007 10:57 | |
| Ben Bangert | 27 Feb 2007 11:36 | |
| Mike Orr | 27 Feb 2007 11:43 | |
| primco | 27 Feb 2007 16:33 | |
| Mike Orr | 27 Feb 2007 16:48 | |
| Mike Orr | 27 Feb 2007 23:01 | |
| Christoph Haas | 28 Feb 2007 00:53 | |
| Graham Higgins | 28 Feb 2007 06:15 | |
| Bob Ippolito | 28 Feb 2007 06:56 | |
| Mike Orr | 01 Mar 2007 14:39 | |
| Ben Bangert | 01 Mar 2007 16:44 | |
| Graham Higgins | 02 Mar 2007 00:25 |
| Subject: | Re: ConceptsOfPylons and Pylons Documentation |
|---|---|
| From: | Ben Bangert (ben-...@public.gmane.org) |
| Date: | 02/27/2007 11:36:28 AM |
| List: | com.googlegroups.pylons-discuss |
On Feb 27, 2007, at 12:58 PM, Christoph Haas wrote:
Mine, too, especially since I mainly wrote it. :) AFAIK there is a plan to write a more complete handbook for Pylons at http://pylonshq.com/project/pylonshq/wiki/DocLayoutProposals
Unfortunately I'm still too much a newbie to contribute to most parts of that planned guide. So I fear that such a documentation won't be written for quite some time. I hope to see my article get a place in the final documentation though.
A lot of background docs are needed to. For example, while I can easily explain how to use sessions, and that kind of thing there's background writing that should be filled in (what are sessions, db- based vs 'dumb' stores that are pickled data, etc).
Yes, there seem to be only few people who have permission to change that part of the documentation. I still like to offer help in that area because there is much more to learn about Pylons than is documented where people would look for it.
In theory, once you login, any part of the wiki docs can be changed, I assume this is refering to the Docs section that is not in Trac?
Same here. Smells like missing permission to change that page. <rant>I don't like the documentation part of the pylonshq website anyway. Splitting the documentation across both the "Docs" and "Wiki" parts is confusing.</rant> It would really help to make it clear where you find the needed handbook, where to download the software and where to get support. I've heard rumors that not even the website maintainers are completely happy with the Trac the way it is. :)
I've hit that once or twice, hitting reload usually fixes the issue. I've had quite a few issues with Trac's wiki, while the rest seems to 'usually' work. The docs are generated based on ReST docs in the Pylons svn repo, which makes it cumbersome to edit them collaboratively. Though the benefit is that when I merge them into the 'official' docs I usually try to clean them up and do a few style bits here and there to make them fit in a little better.
Splitting the docs across both parts, especially with the wiki based docs growing is definitely confusing. At the same time, unless people can take ownership for sections of the wiki docs its hard to recommend them as I have no idea if they're accurate, up-to-date, or actually work.
I think at this point, I'm looking at moving all docs to a Moin wiki, and cloning it to handle doc updates (ie, the 0.9 docs will be one wiki with its pages 'frozen', while 1.0 will be another so that people can get to both). This way people can fill in the sections they want to talk about, and hopefully others will edit them for grammar/spelling and try to ensure the 'tone' is fairly consistent.
If anyone would like to volunteer for any of these aspects (editing, copyediting, grammer/spelling police, etc). Please let me know. :) Also, those interested in writing more 'generic' sections, like background pages on database sessions vs 'dumb' sessions, what is MVC, how does it apply in Pylons, etc. raise your hand.
Cheers, Ben