[wp-docs] Introduction

[Geof F. Morris]

Hey all:

Well, I guess I should typecast myself.

Howdy.

[I am from Alabama, after all.]

I'm Geof Morris, gfmorris on the forum.  Been weblogging for over two 
years.  I'm an aerospace engineer by academic training, a 
jack-of-all-trades project office weenie by vocation, geek by leaning, 
spastic by birth.

Relevant[?] Experience: Helped run the Greymatter Support Forums back in 
the day, and I remember when Michel first started talking about b2.  [We 
bounced ideas back and forth.]  I wrote and re-wrote some of the GM 
documents, so I have opinions on How It Should Be Done.

But I'm flexible.  Just don't ask me to put my foot behind my head--last 
time, I got stuck.

I think we can work at the documentation needs from two ends:

1.  New User Documentation: as discussed on the list archives [gotta 
love Mailman ... I read everything before starting this email ;)], a 
light-hearted voice is par for the course on the project so far, and it 
seems to make sense to keep it going.  I think we can focus on very 
simple, practical, absolutely-spelled-out-to-the-Nth-degree stuff.

Yes, that's tedious as HELL to write, but you know, it's worth doing in 
the long run.

2.  Functional Documentation: Each new function needs to be documented 
[and I think it already all is in the readme] and then, as practically 
as possible, implemented on a test site so examples can be shown.  
[People will ape code if they know what it does.]

A thought that I've had is to have a working WP install with multiple 
templates on it that show the various ways that functions can be used.  
Now, I don't think that we have to go scientific method on it and hold 
all variables constant save one for each template, but ... yeah.

I'll be offline at my grandmother's [extremely rural Alabama ... no 
broadband] for a couple days, and I'll sketch out some of this then.  
Verbosity is par for my course, and sometimes, I just do better when I 
can show than tell.

...

All this isn't to say that FAQ's and HOWTO's aren't helpful, because 
they are ... but I think a holistic approach makes documents more 
understandable to non-technical people.

GFM <-- doing this project purely so he can learn what all the vars and 
functions do ... that's how I learned GM, dadgummit!