[wp-hackers] Documentation revisited (follows scriptygoddess next - previous post discussion)

[jill]

ayj & j wrote:

(liberal and ill-marked snippage has occured, my fault entirely)

>1. IMO the Wiki, or indeed the WP documentation in general, does not work
>remotely adequately for plugin writers, nor is there much sign that it ever
>will.

okay.

>2. I think there is value in plugin writers cooperating on creating some
>documentation / sharing ideas / having a process for asking and sharing
>knowledge about specific issues.

I agree.

>3. The needs and objectives of plugin writers and those of the main WP
>developers are not the same nor are they always aligned identically.

for sure.

>On the basis of those comments, I think it could make sense for the plugin
>writers to cooperate in creating some useful documentation as part of their
>own plugin development - independently of the main WP documentation effort.
>Perhaps such an approach can contribute to the main documentation at some
>stage but that is a separate issue.

I agree, again. What I'm not clear on is, how would this look different from the wiki? It seems
to me that a wiki-structure is tailormade for people to contribute articles or snippets, long or
short, as their time, abilities and interests permit. This particular wiki may not be optimally
structured for your or my or anyone else's contributions, but at least in theory, wikis are the
form for facilitating free-ranging additions from a wide variety of authors with a minimal
amount of administrative overhead.

>I would like to
>see us create a highly annotated / commented version of the WP scripts, with
>individual line comments within this special hackers script set, and with
>the ability to post more detailed discussion underneath each individual
>annotated script. Much along the lines of the php on-line manual. Perhaps
>each 'detailed discussion post' could also be circulated on a mailing list,
>this one or another if that is considered more appropriate.

This sounds very nice, provided the WP functions themselves have reached the point
where they are unlikely to change their names or their parameters from one release to the
next. Or if they do, that there'll be enough time between releases to make such annotation
of lasting benefit anyway.

pericat
-- 
<http://pericat.ca/>