Great work, Karl. I was thinking along similar lines. "RoughDocs" is the place to toss random stuff until an editor comes along and moves it to the real deal in a place that makes sense.
Kevin On Aug 27, 2006, at 2:30 AM, Karl Guertin wrote: > > One of my peeves when it comes to documentation (and any information > design, really) are junk drawers, the places you dump random docs. The > problem with these is that you always have to check the junk drawer > when you're looking for stuff just in case it might be there. The > 'other docs' section on the 0.8/0.9 site is one such junk drawer. > > I've taken the liberty of rearranging the structure of the main 1.0 > page in order to hopefully make it easier for people to find what > they're looking for, it's basically arranged along the path that I > imagine a new user will go through: > > Getting Help > Now first, I like sites that put getting help first, I think it's > respectful. > > Installation > As before, recommend an, 'offline install' section > > Tutorials > As is, low level overview of system, answers "what does it look like" > and provides a guide-type starting point > > Getting Started > The minimal amount that you need to know, suggest combining tg-admin > and Starting Server into 'Starting Up' or somesuch > > How do I do ____ in TurboGears? > How-to section, many of the 'Getting Started' sections now live here. > I'd like to see the docs here be a background/why do I care followed > by a quick overview of what TG provides and a pointer to the full > docs. I'm slightly concerned with this becoming the new junk drawer, > but hopefully we can keep this to 15 items or so. Kind of like an FAQ > with extended answers. > > API Reference > How is this coming along? I notice that most of the modules have > fairly good docstring coverage. > > Off-site Component Documentation > Links Elsewhere > > TurboGears, In Detail > The full documentation, but not a pedantic coverage (that's what the > API docs are for). > > Deployment > As before > > TurboGears for Hackers > Project docs, apis, plugins, etc > > Appendix > As before > > I've broken my reworking into two sections. One is the splitting of > Other Documents (which I don't think people will disagree with) and > the other is reworking Getting Started, which is more subjective. I > feel that the new organization is superior in that every section has a > purpose and hopefully they're arranged in a fashion that lets people > scan down to find exactly as much or as little as they want. > > > -- Kevin Dangoor TurboGears / Zesty News email: [EMAIL PROTECTED] company: http://www.BlazingThings.com blog: http://www.BlueSkyOnMars.com --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
