[wp-docs] [Dev Doc] WordPress Database Reference

[Carthik Sharma]

Owen's suggestion of seperating function references from How-Tos seems
to be good. For now, maybe we can have both the name of the function
and the text that describes how it can be used as the section heading?

What we have started here is not an easy task to accomplish with
respect to organization, the best we can do is try out different
things and settle on what seems to be good, which should not be a
problem in itself.

Carthik


On Tue, 15 Mar 2005 09:00:38 -0500, Owen Winkler
<ringmaster at midnightcircus.com> wrote:
> Michael D.Adams wrote:
> > I've got a rough sketch of the wpdb class at
> > http://codex.wordpress.org/User:MDAWaffe/Functions .  I agree now that
> > the content is better served from the [[WordPress Function Reference]]
> > section.
> 
> This page looks fairly complete.  My only thought (and don't take this
> as a negative, since I may still come around to this idea) is that I
> find the functional function references a bit unnerving.  (Functional
> function references = Titling a function by what it does rather than
> using its name.)
> 
> What I imagine might be optimal from an end-user/developer point of view
> is an actual "reference" with just the function definitions and
> parameters, and then a how-to for each section that links to the reference.
> 
> I'm rambling here because there's an alarm going off in my intuition.
> Is it a false alarm?
> 
> > The sections delineated there were completely off the cuff.  Please
> > organize things differently if you see a better alternative.  In
> > particular, what do people think about each class (or natural group of
> > classes) getting its own box on the page? Also, I don't really know what
> > "basic functions" could be; functions from functions.php will probably
> > go into several categories.  Again, edit at will.  Owen, you seem to
> > have a good idea how things should be organized.  Do you mind poking the
> > page or listing a sectional hierarchy here?
> 
> Using the core filenames seems like a logical way to break up the larger
> sections, but I wonder if there are subsection groupings that make
> sense.  Like in my last message on this topic, I was talking about
> Options functions.  This grouping isn't large enoguh (the three
> functions currently in [[Writing a Plugin]]) for it's own major heading,
> but where does it go?  In which of these sections would you look for it?
> 
> I require more thought on this yet.  Maybe I just need to break it out
> and do it to see what it looks like.
> 
> > This brings up the subpage issue.  It seems the best way to implement to
> > me, but I'm open.  I suppose, then, each of the functions I describe for
> > the wpdb class should have its own page, with an umbrella page
> > describing database interface in general, the class variables, and the
> > class as a whole.
> 
> I think maybe that's what I was trying to say at the beginning - I would
> put the class reference on one page, and then have the description of
> the interface along with a few examples on another.  I don't know if I
> would put each function on its own page, though - that would seem to
> spawn a lot of clicking around.
> 
> For example, there could be a developer reference page, [[Accessing the
> Database]] that describes the interface and how to use it in general
> which has support function reference on [[wpdb Database Class]] (or
> whatever you want to call your current [[User:MDAWaffe/Functions]]).
> Perhaps the function reference could be embedded in the developer
> reference page, or maybe a simple link would suffice.
> 
> Similarly, I'd rip out the "#Saving Plugin Data to the Database" section
> from [[Writing a Plugin]], replace it with concrete examples that link
> to the ripped out stuff as a pure function reference.
> 
> I'm just looking at this from my perspective versus newbie devs.  For
> me, I want to skip the "How-to" page and just get the function
> parameters or whatever.  I don't want a lot of prosy stuff in the way of
> what I want to know, yet that stuff may be more important for others
> than the function reference itself.
> 
> Owen
> 
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
> 


-- 
When nothing is done, nothing is left undone -- 老子 Lǎozi

University of Central Florida
Homepage: http://carthik.net