Here's a few things I've come up with (but haven't had time or in some cases knowledge to work on):
the "Identity source" problem: On the Configuration <http://docs.turbogears.org/1.0/Configuration> page the entry for "identity.source" refers the reader to the IdentityManagement<http://docs.turbogears.org/1.0/IdentityManagement>page for more detail. Which doesn't exist. Further searching by the determined reader will find that the page title for the identity docs is misspelled and is actually at IdentityManagment<http://docs.turbogears.org/1.0/IdentityManagment>(notice the missing "e"). Great, I found it! Wait...there is nothing on that page regarding config options for identity... This kind of thing is really frustrating, even for us "old hands" who've been using TG (off and on) since 0.8. This isn't the only example of this I've seen, but its the only one I can find right now, so the others are either hiding or have been fixed already. Other configuration docs issues: 1) the links to the CherryPy config docs are broken 2) more detail would be nice in a few places, as I think this will be a critical section for new users. 3) a mention that the config files are heavily commented might be nice, so people could look there if they don't find what they need 4) some of the config options list defaults, others list valid values, others don't list anything. To use the config system people will need to know a) what the option is for b) what values they can put for the option c) what effect those options will have on their application. The current docs are lacking somewhat in their thoroughness. If you can't tell, I'm on a config kick this week... [BTW, I'm not saying the configuration page is _bad_! Please don't get that impression! I actually stood up and yelled in delight when I saw that it was added and it's been a great reference. But I think it could be (and should be) better. At least in a couple of places. Overall it's great though.] Startup/shutdown of a TG app: I've always wanted to know a little more about what goes on behind the scenes here...would e nice to have a short writeup of this, but not too critical for most people. Introductory paragraphs: The current docs are somewhat inconsistent in the use of intro paragraphs on each page. Some have great intros into their topic (for example: Configuration :) Other pages seem to assume that you already know what the author is talking about. This is mostly a stylistic thing, but I think the doc authors need to keep in mind that readers won't necessarily know anything about TG (what is a Widget in TG terms? What is SQLObject? Who is MochiKit?) and also that readers may not have seen the index/FrontPage when they start reading. Also, users may get linked into the middle of a page from somewhere, so little reminders as to what's going on in the page might be nice. Of course, if you do to much of this, you end up repeating yourself A LOT, so a balance must be struck. Widgets docs: (...but you already knew I was going to say that...) This is critical, as knew users seem to have the most problems with this. I especially think that the widget browser needs some cleaning up (though it has been improving), as has already been mentioned in this thread ("Source code" and "tempalte" sections are misleading to new users). More detail on individual widgets would be good too...even if it's just a reference. Home link: All pages should have a link to the home page of the wiki. Currently its easy to get to the root of the TG version you are looking at, but not so easy to get to another version. This isn't such a big deal yet, but will be when 1.1 and 2.0 are released. I'm sure I could come up with more, but then I wouldn't get any other work done, so that's it for now. Kevin Horn On 2/4/07, Mark Ramm <[EMAIL PROTECTED]> wrote: > > I'd like to hear the specifics of what you think needs attention in > the TurboGears Documentation. > > On my list for most important Documentation issue right now is the > fact that we haven't been successful in getting API docs generated by > PythonDoc, or Epydoc. > > Beyond that, I think we could use some good "orientation" > documentation which provides the big picture overview. Much like the > old Getting Started Guide did. > > And people always seem to need better Widget Documentation > > What else needs to be covered or covered better? > > -- > Mark Ramm-Christensen > email: mark at compoundthinking dot com > blog: www.compoundthinking.com/blog > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears Docs" 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/turbogears-docs?hl=en -~----------~----~----~----~------~----~------~--~---
