On Tue, Jun 30, 2009 at 1:26 PM, Michael Pedersen <[email protected]> wrote:
> On Tue, Jun 30, 2009 at 1:44 PM, Kevin Horn <[email protected]> wrote: > >> I like this pretty well, though I have a couple of suggestions > > > Thank you. Suggestions are always welcome. > > >> - this is a small thing, but I'd like to see the headers on the front page >> be a little more prominent. > > > I'm still new enough with the restructured text that it's easy for me to > have gotten the formatting wrong, or badly done. Personally, I'm not happy > with the headers being in italics. So, I'm still working on it. > > Since it bothers other people, I'm going to add it to my TODO list for the > docs. > > - a much bigger deal is the link to the Extetended TOC needs to be obvious >> and at the top of the page. perhaps in a "note" or something. The friendly >> narrative stuff you have going is great for new people, but there needs to >> be a shortcut for people who know where they are going and are using the >> docs as a reference. >> > > The Extended TOC is something of an issue for me. I'm using it right now > because I haven't managed to reorganize everything the way I like. In the > end, I want it to go away entirely. Before you think I've lost my mind, I do > have a reason. > > My goals for this reorganization are threefold: > > 1. From the front page of the docs, it should be possible to reach *any > * page with no more than 5 clicks. 3 is the ideal, though that might be > overly ambitious. > 2. From the front page of the docs, a person new to TG should be able > to find what they are looking for within 90 seconds (that's across all of > those 5 clicks, too). > 3. The docs should still make an effective reference for those who > already know what they, and just need a quick refresher on some specific > item. > > If you take a look at the extended TOC, you'll see that it's already mostly > unnecessary. Check the source at > http://bitbucket.org/pedersen/tg_2_1_docs/src/tip/docs/toc.rst and you'll > see that, for almost everything (the Rough Docs being the only exception), > each section is just a table of contents for one of the pages linked off the > front page (tutorials, up and running, etc). > > As such, it doesn't look like you would save any time, not even one single > mouse click, by going for the extended TOC. > > The 90 seconds I mentioned above is for new users. For experienced users, > who don't need to read the intro paragraphs, should be looking at the docs > they need within 45 seconds, max, and 30 seconds, ideally. > > So, what do you think? With those goals in mind, should I even focus any > efforts on the extended TOC, or just let it die out naturally when I reach > near the end of this set of updates? > > >> BTW, thanks for doing this, overall I think it's a great improvement (so >> far). >> > > Thank you. It's still very much in an infancy type stage, but it is at > least a bit easier to find things so far. At least, I think so. > > -- > Michael J. Pedersen > My IM IDs: Jabber/[email protected], ICQ/103345809, > AIM/pedermj022171 > Yahoo/pedermj2002, MSN/[email protected] > I still think you've lost your mind ;) For me at least, I think it's very helpful to have a single TOC listing everything on one page. I often find myself scanning a TOC to find something (usually when it's something I've read before, but I can't remember where it is). Since Sphinx can handle this pretty much automatically, I don't see any reason not to offer it as a resource to readers, though I think we both agree that it should be a reference tool, rather than an introduction. I think what I'd really like to see is a link in the navigation section (with the "previous" "next" "index" links), but others may disagree. Kevin Horn --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears Trunk" 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-trunk?hl=en -~----------~----~----~----~------~----~------~--~---
