[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:         
Component:  WordPress.org                     |      Version:  2.7    
 Severity:  normal                            |   Resolution:  wontfix
 Keywords:  search theme documentation codex  |  
----------------------------------------------+-----------------------------
Changes (by jacobsantos):

  * milestone:  2.8 =>

Comment:

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

 Yes, if the inline documentation is incorrect, then it is a bug worth
 posting to Trac. Since the very nature of the Codex as a Wiki, which
 allows anyone to sign up and edit it. There is really no point to say,
 "Hey fix this," when the person saying that can fix it themselves.

 Really, the only page that it should be corrected on is the function
 reference or [http://codex.wordpress.org/Template_tag/get_search_form
 template tag], depending on which it falls under. Summaries like the page
 you referenced, should not go into a lot of detail, so an example on that
 page would not be advisable.

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

 The Codex doesn't say a lot of things that it should. It is like DD32
 said, a completely volunteer effort, and it is a lot of effort. So
 basically, you have a group of awesome people working as hard as possible
 to document what '''they feel like.'''

 So I mean, take you for example. You care about the get_search_form()
 function issue, so someone like you would create the template tag page,
 add the details, and then leave it as a stub for others to finish later.
 Or you could finish it.

 Part of the reason for the inline documentation effort was that the Codex
 doesn't have everything and is often inaccurate about functions you are
 describing. Also, phpdoc.wordpress.org exists, and that is also a
 wordpress.org site, which has correct information. You can not however,
 easily edit it. Well, you can't edit it, unless you create a patch for the
 inline documentation in the source.

 That does remind me to document the HTTP API. Just so boring, I'm sure
 people will figure it out, eventually. Maybe. Yeah, I should probably
 write it.

 > > 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.

 Why? I can spend close to about 10 to 30 minutes creating patches for
 simple tickets and spend up to 3 hours on more difficult ones. What makes
 you think I have time to search the codex to fix the various locations or
 document what I've done? To me adding inline documentation is as far as I
 need to go.

 Likewise, a Codex page can also take up to three hours, so it evens out.
 If I was being paid, then yeah, I would probably spend the time to
 document what I was doing.

 > 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.

 It is also part of the reasons for adding inline documentation to the
 source code of !WordPress. A novice may not understand the importance of
 documentation, until they see if first hand. DocBook and PHP.net style
 documentation like the Codex is somewhat out there until you reach a
 higher level. I will say that inline documentation is good enough in most
 cases.

 That said, I do care about !WordPress. I care about !WordPress being
 stable and having the features I care about. I do also care about being
 able to build plugins and having documentation in place, which is why I
 started documenting more on the Codex. However, I find it difficult to
 justify spending an hour to 3 hours writing about something on the Codex.

 > 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.

 You're not going to change anyone's mind. Go to wp-docs mailing list
 instead.

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