[documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting

[Mr. Meitar Moscovitz]

On Jun 3, 2008, at 12:03 PM, Angela Byron wrote:

> Mr. Meitar Moscovitz wrote:
>
>> Either way, now I know what the proper places for things like this   
>> are. Thanks!
>
> Just as a general statement, Meitar, you're asking really great  
> questions that I'm sure all newcomers to the docs team are going to  
> struggle with. How would you feel about making a "Documentation  
> Contribution FAQ" or something like that that, which contains a list  
> of the questions you asked and the answers you've gleaned from the  
> list, in words that a fellow new contributors like yourself could  
> understand? I'd be happy to proof-read it for you, if you'd like.

That makes sense to me. I'm sure most of the answers to such questions  
already exist in many places, but in all the places that I've found  
what turned out to be correct answers, they were pretty brief and hard  
to interpret. For instance, here, in "Updating API documentation" http://drupal.org/node/144223 
  there's a short section headlined "Code" that has two sentences in it:

> All documentation for core functions, constants, and files are  
> automatically generated from the core modules in Drupal. […] To  
> update these, you must submit a core patch to edit the Doxygen  
> comments of the code in question.


The text "submit a core patch" is a link to the http://drupal.org/node/add/project-issue/drupal 
  page, which is far from explanatory for someone like me (until  
yesterday, when Steven clued me into the details). Better, IMHO, would  
be a paragraph or two (tops) with appropriate links embedded in  
natural text to places such as "Doxygen formatting conventions" (http://drupal.org/node/1354 
) and so forth, so the reader doesn't have to reach for the search box  
in a ridiculous number of browser tabs. :)

So I guess my question is, do you think there's really a need for a  
FAQ, or should I just spend a little while going through some of the  
child pages to "Contributing to documentation" and fleshing them out  
further?

Of course, I could always do *that*, and then *also* compose a list of  
all the questions I'm asking, run them by you or a mailing list  
archive search to see how frequent they are, and then post brief one- 
liners with appropriate links in a new "Contributing to documentation  
FAQ", as well….

> You don't have to, of course, but it just seems like it'd be great  
> to get these things written up somewhere so the *next* time it  
> becomes "Oh, that's covered in the FAQ at <link>. See question #2." :)
>
> -Angie


I didn't have to ask to join the Drupal docs team either, now did I? ;)

Cheers,
--
-Meitar Moscovitz
Drupal: http://drupal.org/user/265715
Personal: http://maymay.net
Professional: http://MeitarMoscovitz.com