[wp-trac] Re: [WordPress Trac] #8799: get_search_form() is inadequately documented

[WordPress Trac]

#8799: get_search_form() is inadequately documented
----------------------------------------------+-----------------------------
 Reporter:  sampablokuper                     |        Owner:         
     Type:  enhancement                       |       Status:  closed 
 Priority:  normal                            |    Milestone:  2.8    
Component:  WordPress.org                     |      Version:  2.7    
 Severity:  normal                            |   Resolution:  wontfix
 Keywords:  search theme documentation codex  |  
----------------------------------------------+-----------------------------
Comment (by sampablokuper):

 Replying to [comment:11 DD32]:
 > sampablokuper: Is it a Documentation error on the Codex, Or a bug within
 the Core WordPress Code?

 The former.

 > Bugs in the core code belong on Trac (Or Documentation errors in the
 actual Inline documentation in the PHP), Codex documentation issues do not

 That's a pretty unenlightened view, IMO. Ubuntu has shown that "bugs"
 [https://launchpad.net/ubuntu/+bug/1 aren't just about the code].

 Furthermore, I reported this as an enhancement to wordpress.org (which
 contains the Codex in one of its subdomains), not as bug in the core code.

 >Change it yourself

 If I can spare the time, I may yet do this. But without raising the issue
 with others, I wasn't able to find out what to change it to.

 >Go to the support forums or post on the
 [http://lists.automattic.com/mailman/listinfo/wp-docs documentation
 mailing list]

 I did go to the forums, as you will see if you follow the references in
 the ticket. It's true that I could have posted to the mailing list, and
 maybe that would have been the least controversial course of action, but I
 still don't think the ticket was wholly inappropriate, for the reasons
 I've given above.

 > Do not assume just because the codex doesnt say it, that its a bug,

 I don't. But if the Codex ''should'' say something, and it doesn't, then
 that is a problem. That's what I reported.

 > You not understanding how the API works is not a bug,

 I agree, but this wasn't just about my understanding of the API. It was
 about a new feature in 2.7 whose intended purpose was at least partly
 unclear, and which was documented in a manner that made the status of
 searchform.php (i.e. whether it was deprecated or not) confusing.

 > The groups of people who work on the Code, and those who work on the
 Codex are 2 completely separate groups of people,

 That's a great pity. I'm genuinely very sorry to hear it.

 > Very few of either are payed to do that, and as such, Most people will
 not communicate between each other,

 I don't understand this point at all. Surely a volunteer coder who learns
 to document her code in the Codex is a greater asset than one who doesn't
 learn to do this. So I don't see why volunteers who care about WP wouldn't
 want to learn to do this.

 > Those doing Documentation work follow the WordPress development, and
 update the codex if need be, If a Developer comes across a Codex page
 thats severely out of date, they may fix it themselves, or post a message
 to someone else on the before mentioned locations to get it fixed up.

 That's better than nothing, but there's evidently still quite a lot that's
 out of date.

 > (This is not to say that there are not developers who do both developing
 and documentation, Nor that there is -no- communication, I've had people
 who write documentation contact me numerous times asking for some info on
 a item so they could document it well on the codex)

 Good to hear!

 > Also, Please don't get into re-open wars, If its closed, Someone has
 closed it '''for a reason''',

 But not always a good reason...

 Don't worry, I'm not trying to start a war here. I just don't think my
 ticket was inappropriate. Nor do I think the problem I reported has been
 fixed. Nor do I think the problem should be ignored.

 But you've made it clear that, for the time being, the people who follow
 the Trac mailing list aren't interested in documentation problems. And
 while I think that's a missed opportunity for the wordpress.org community
 (cf. the Ubuntu example above), I'm not going to be able to change
 everyone's minds overnight.

-- 
Ticket URL: <http://trac.wordpress.org/ticket/8799#comment:12>
WordPress Trac <http://trac.wordpress.org/>
WordPress blogging software