[documentation] Forms API handbook volunteer

[Sameer Siruguri]

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> 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>:
> > 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> 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>:
> >>
> >> > 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/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20090227/ff9f42b9/attachment.htm