[wp-docs] Structure of documentation

[Andrew Rivett]

Hello Martin and Jennifer,

I have also recently started using Wordpress and developing plugins for it
as well. I really like the features of Wordpress and how clean and smooth it
is.  I did however have some of the same problems that Martin did in finding
documentation.  In writing a couple of plugin's, which I hope to release
once I clean them up enough, I had a couple of ideas which I was thinking of
working on and contributing to the documentation.

1.  A complete plugin example that is "perfect" in the eyes of Wordpress and
if followed you will write excellent plugin's.  What I am thinking is
perfect syntax, layout, code style,  and documentation.  The document has
snippets of code, but not a complete example.  I typically follow example
code when learning a new system, and didn't know what was good plugin code
and bad plugin code in the eyes of the Wordpress development team.

2.  A 10 step guide (or how ever many steps are required) to writing a
plugin.  The writing a plugin page is a great start, but I was wanting to
create my own table, and build a management page to manage that data.  This
is where I had to download a couple of other plugin's as examples and hope
they are good examples of plugin style.

As an example of the steps:

Step 1. Setup the meta information.  Give example how to you construct the
author info, author URL, description etc.

Step 2. Define your table definition and build the install function.

Step 3. Write functions to display your data on a website.

Step 4. Administration functions.  How to add, edit and delete data.

Step 5. Hooks and Filters.  How to hook your plugin into the Wordpress
engine.

Step 6. Localization.  How to localize your code.

Step 7. Documentation.  How best to document your plugin so other's can use
it.

I'm not sure if this is just a reorganization of existing information, or if
it's something that should be written from scratch?  I would be glad to help
out with this if you would like.  Having just written my first plugin's it's
all still fresh in my mind.

Thanks for all the great existing docs and spending your time working on
them, it's very much appreciated.

Thanks!
Andrew.

On 2/21/07, Jennifer Hodgdon <yahgrp at poplarware.com> wrote:
>
> Hi Martin,
>
> Excellent!
>
> a) Rewriting the "Writing a Plugin" article was already at the top of
> my To Do list. I might have time later this week. It is definitely a
> bit disorganized, and it should reference (rather than duplicate) the
> Plugin API article.
>
> b) I totally agree that there are a ton of pages that loop around
> endlessly when you are trying to find documentation... believe me, the
> situation was worse a month or two ago! But it still needs
> improvement. I've been focusing my efforts on improving the
> organization of the developer-related documentation, removing
> duplicated information, making central places to look for information,
> etc. But more does need to be done. I've made notes of your specific
> points, but you can feel free to jump in and improve things too.
>
> c) Function Reference:
> > I'm not aware of the history of this page, but according to your
> > reaction, I assume that in the past there was not such a reference.
>
> There was a reference page before, but it was missing about 75% of the
> functions. Jump in and add documentation and organization at will!
> Please! :) You also mentioned some kind of Table of Contents -- the
> Wiki makes it easy to add links down the page, so that can be added
> too. Good idea!
>
> d) Here are 3 places that I think need more documentation in the
> developer reference area, if you want to help:
>
> 1) Function Reference - each function should at least have a short
> description, and better yet a documentation page. Better categories
> might be useful too, or maybe listing functions in more categories.
>
> 2) Template Tags - add the rest of the functions from the
> *-template.php files, so that the lists are complete, and document
> functions that are lacking documentation currently. Right now, only a
> subset of the functions are on the page, and it seems quite arbitrary.
> Note that some functions are on separate pages (like the Conditional
> Tags and the Include Tags).
>
> 3) Hooks list - document these hooks, perhaps organize them into
> categories?
>
>       Jennifer
> --
> Jennifer Hodgdon
>
> Poplar ProductivityWare * www.poplarware.com
> Web Databases/Scripts * Modeling/Analysis/Palm OS Software
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>



-- 
Be the change you want to see in the world -- Mahatma Gandhi
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://comox.textdrive.com/pipermail/wp-docs/attachments/20070221/a5726e20/attachment-0001.htm