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

[Steven Jones]

Hi,

I'd imagine writing a FAQ by yourself would be a huge undertaking, instead,
why don't you create an issue in the queue (documentation project) and just
list any questions that you can think of, others can do the same and then
gradually we can move them over into handbook pages. If we make each
question its own page then the handbook theming will give us a nice list of
all of them on the parent page.

If there were a list of 'Unanswered FAQs'  then I'd happily spend ten
minutes every now and then writing an answer to one and adding it. If
other's did the same we'd get a high quality FAQ list in no time.

On Tue, Jun 3, 2008 at 12:11 PM, Mr. Meitar Moscovitz <meitarm at gmail.com>
wrote:

> 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
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>



-- 
Regards
Steven Jones
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20080603/eaaa785c/attachment.htm