[documentation] Forms API handbook volunteer
Steven Jones
darthsteven at gmail.com
Wed Mar 4 03:45:10 UTC 2009
Hey everyone,
I'm wondering if anyone wants to meet up at Drupalcon to discuss this,
maybe at the documentation sprint?
The task of documenting FormAPI is a massive challenge, but I like the
idea of documenting examples, explaining the ways that the examples
work, and what they do.
Regards
Steven Jones
ComputerMinds ltd - Perfect Drupal Websites
Phone : 0121 288 0434
Mobile : 07951 270 026
http://www.computerminds.co.uk
2009/2/27 George <g at 8vue.com>:
> i'd like to suggest, examples. ie. a simple fapi array gives what type
> of element / form? a lot can be inferred from a simple example that
> would take many more words. and the example only needs to cover the
> point of the example, so, if you're discussing setting up a textfield,
> then no need to create the whole form, just that element.
>
> also system_settings_form is a great helper function ;)
>
> i also think the reference chart for fapi is a great resource once
> you've got the basics.
>
> thanks
>
> Sameer Siruguri wrote:
>> Steven,
>>
>> the feedback I have seen on different forums is not very detailed --
>> it's mostly of the sort, "I wish there were more
>> detailed/comprehensive documentation about forms."
>>
>> One proposal I have is that we start putting something out there and
>> see how people react to it, sort of a wiki style of doing it, where we
>> incorporate comments over time once there is something to comment to.
>>
>> Alternatively, we could canvas some of the people who have commented
>> on various Drupal related websites about the difficulty of getting
>> comprehensive documentation and ask what they are lacking.
>>
>> I think the spectrum will be fairly wide in terms of expertise people
>> who are looking for Forms docs already have, but I wouldn't be
>> surprised if many of them are newbies trying to get to grips with the
>> basics. As Nancy notes, there will also be people looking to do
>> dynamic elements and multi-stage forms.
>>
>> One idea I had was to first create the detailed description of
>> _everything_ the API does, and then write an FAQ for some of the
>> common-case tasks, that point to entries in the detailed description.
>>
>> Thoughts?
>> Sameer.
>>
>>
>> On 2/27/09, *Steven Jones* <darthsteven at gmail.com
>> <mailto:darthsteven at gmail.com>> wrote:
>>
>> Essentially, before launching into the massive effort of documenting
>> FormAPI, we should have the discussion: 'What should we document'.
>>
>> You mention: "lots of folks have been commenting on the lack of
>> something good". What are they after? Are they newbies getting to
>> grips with forms? Are they experienced developers wanting to do more?
>>
>> Can anyone suggest what the FormAPI docs should cover?
>>
>>
>> Regards
>> Steven Jones
>> ComputerMinds ltd - Perfect Drupal Websites
>>
>> Phone : 0121 288 0434
>> Mobile : 07951 270 026
>> http://www.computerminds.co.uk
>>
>>
>>
>> 2009/2/26 Sameer Siruguri <siruguri at gmail.com
>> <mailto:siruguri at gmail.com>>:
>> > Steven,
>> >
>> > good to hear from you. I cannot make DrupalCon in DC, more's the
>> pity. I am
>> > interested in learning more about your views on how to properly
>> document the
>> > Forms API. Did you mean to say that the outline written by
>> Steven Peck is
>> > the one you have some doubts about? Or just the general style of the
>> > content?
>> >
>> > I am interested in getting content out there asap, lots of folks
>> have been
>> > commenting on the lack of something good. Personally, I think
>> having an
>> > explanation of the steps inside drupal_get_form (process,
>> prepare, alter,
>> > render, etc.) would be very useful, esp. for ninja developers.
>> It's easy to
>> > get things mixed up if you don't know the exact order in which
>> these steps
>> > are called, including the parts where weights get sorted out,
>> and when
>> > pre/post_render functions get called.
>> >
>> > I would love to discuss some of these over email, if that's
>> possible, or of
>> > course, to hear more about what you learn at DrupalCon.
>> >
>> > Cheers!
>> > Sameer.
>> >
>> > On 2/26/09, Steven Jones <darthsteven at gmail.com
>> <mailto:darthsteven at gmail.com>> wrote:
>> >>
>> >> Hi Sameer,
>> >>
>> >> I actually was just the last person to edit that page, the
>> content is
>> >> down to Steven Peck.
>> >>
>> >> In any case I'm not sure that documenting FormAPI like that is the
>> >> best way to go. Like you I've wanted to document FormAPI better
>> for a
>> >> while now, but I'm not sure the best way to approach it. Maybe we
>> >> could gather a few interested parties at Drupalcon D.C. and have a
>> >> little chat about the best way forward.
>> >>
>> >> Are the any other's who'd be interested in helping out with
>> FormAPI docs?
>> >>
>> >> Regards
>> >> Steven Jones
>> >> ComputerMinds ltd - Perfect Drupal Websites
>> >>
>> >> Phone : 0121 288 0434
>> >> Mobile : 07951 270 026
>> >> http://www.computerminds.co.uk
>> >>
>> >>
>> >>
>> >> 2009/2/26 Sameer Siruguri <siruguri at gmail.com
>> <mailto:siruguri at gmail.com>>:
>> >>
>> >> > Hi,
>> >> >
>> >> > I have been interested in fleshing out, and collating, the
>> documentation
>> >> > for
>> >> > the Forms API for some time now, and recently got started on
>> writing out
>> >> > the
>> >> > material that would go under the headings that Steven Jones
>> wrote out on
>> >> > this page: http://drupal.org/node/204270 (Here's a page I
>> wrote, with
>> >> > one
>> >> > child: http://drupal.org/node/384120)
>> >> >
>> >> > Here's the problem I ran into: After writing some pages down, I
>> >> > sheepishly
>> >> > realized that some material already existed as child pages.
>> But I don't
>> >> > have
>> >> > edit permissions to the top level of those child pages, which
>> makes it
>> >> > hard
>> >> > to incorporate some of my changes and esp. to consolidate all the
>> >> > material
>> >> > at the top level.
>> >> >
>> >> > Here are some solutions: I could go ahead and build out all
>> the material
>> >> > and
>> >> > then propose a consolidation. I could build it on my own
>> website and
>> >> > find
>> >> > some way to export the book to be imported into Drupal.org. I
>> could have
>> >> > access to the top level pages. I could do something during
>> DrupalCon.
>> >> >
>> >> > I am open to suggestions. Thanks!
>> >> > Sameer.
>> >> >
>> >> >
>> >>
>> >> > --
>> >> > Pending work: http://drupal.org/project/issues/documentation/
>> >> > List archives: http://lists.drupal.org/pipermail/documentation/
>> >> >
>> >> --
>> >> Pending work: http://drupal.org/project/issues/documentation/
>> >> List archives: http://lists.drupal.org/pipermail/documentation/
>> >
>> >
>> > --
>> > Pending work: http://drupal.org/project/issues/documentation/
>> > List archives: http://lists.drupal.org/pipermail/documentation/
>> >
>> --
>> Pending work: http://drupal.org/project/issues/documentation/
>> List archives: http://lists.drupal.org/pipermail/documentation/
>>
>>
>> ------------------------------------------------------------------------
>>
>> --
>> Pending work: http://drupal.org/project/issues/documentation/
>> List archives: http://lists.drupal.org/pipermail/documentation/
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
More information about the documentation
mailing list