Steven,<br><br>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."<br><br>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.<br>
<br>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.<br><br>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.<br>
<br>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.<br><br>Thoughts?<br>
Sameer.<br><br><br><div><span class="gmail_quote">On 2/27/09, <b class="gmail_sendername">Steven Jones</b> <<a href="mailto:darthsteven@gmail.com">darthsteven@gmail.com</a>> wrote:</span><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Essentially, before launching into the massive effort of documenting<br> FormAPI, we should have the discussion: 'What should we document'.<br> <br> You mention: "lots of folks have been commenting on the lack of<br>
something good". What are they after? Are they newbies getting to<br> grips with forms? Are they experienced developers wanting to do more?<br> <br> Can anyone suggest what the FormAPI docs should cover?<br> <br><br>
Regards<br> Steven Jones<br> ComputerMinds ltd - Perfect Drupal Websites<br> <br> Phone : 0121 288 0434<br> Mobile : 07951 270 026<br> <a href="http://www.computerminds.co.uk">http://www.computerminds.co.uk</a><br> <br> <br>
<br> 2009/2/26 Sameer Siruguri <<a href="mailto:siruguri@gmail.com">siruguri@gmail.com</a>>:<br> > Steven,<br> ><br> > good to hear from you. I cannot make DrupalCon in DC, more's the pity. I am<br> > interested in learning more about your views on how to properly document the<br>
> Forms API. Did you mean to say that the outline written by Steven Peck is<br> > the one you have some doubts about? Or just the general style of the<br> > content?<br> ><br> > I am interested in getting content out there asap, lots of folks have been<br>
> commenting on the lack of something good. Personally, I think having an<br> > explanation of the steps inside drupal_get_form (process, prepare, alter,<br> > render, etc.) would be very useful, esp. for ninja developers. It's easy to<br>
> get things mixed up if you don't know the exact order in which these steps<br> > are called, including the parts where weights get sorted out, and when<br> > pre/post_render functions get called.<br> ><br>
> I would love to discuss some of these over email, if that's possible, or of<br> > course, to hear more about what you learn at DrupalCon.<br> ><br> > Cheers!<br> > Sameer.<br> ><br> > On 2/26/09, Steven Jones <<a href="mailto:darthsteven@gmail.com">darthsteven@gmail.com</a>> wrote:<br>
>><br> >> Hi Sameer,<br> >><br> >> I actually was just the last person to edit that page, the content is<br> >> down to Steven Peck.<br> >><br> >> In any case I'm not sure that documenting FormAPI like that is the<br>
>> best way to go. Like you I've wanted to document FormAPI better for a<br> >> while now, but I'm not sure the best way to approach it. Maybe we<br> >> could gather a few interested parties at Drupalcon D.C. and have a<br>
>> little chat about the best way forward.<br> >><br> >> Are the any other's who'd be interested in helping out with FormAPI docs?<br> >><br> >> Regards<br> >> Steven Jones<br>
>> ComputerMinds ltd - Perfect Drupal Websites<br> >><br> >> Phone : 0121 288 0434<br> >> Mobile : 07951 270 026<br> >> <a href="http://www.computerminds.co.uk">http://www.computerminds.co.uk</a><br>
>><br> >><br> >><br> >> 2009/2/26 Sameer Siruguri <<a href="mailto:siruguri@gmail.com">siruguri@gmail.com</a>>:<br> >><br> >> > Hi,<br> >> ><br> >> > I have been interested in fleshing out, and collating, the documentation<br>
>> > for<br> >> > the Forms API for some time now, and recently got started on writing out<br> >> > the<br> >> > material that would go under the headings that Steven Jones wrote out on<br>
>> > this page: <a href="http://drupal.org/node/204270">http://drupal.org/node/204270</a> (Here's a page I wrote, with<br> >> > one<br> >> > child: <a href="http://drupal.org/node/384120">http://drupal.org/node/384120</a>)<br>
>> ><br> >> > Here's the problem I ran into: After writing some pages down, I<br> >> > sheepishly<br> >> > realized that some material already existed as child pages. But I don't<br>
>> > have<br> >> > edit permissions to the top level of those child pages, which makes it<br> >> > hard<br> >> > to incorporate some of my changes and esp. to consolidate all the<br> >> > material<br>
>> > at the top level.<br> >> ><br> >> > Here are some solutions: I could go ahead and build out all the material<br> >> > and<br> >> > then propose a consolidation. I could build it on my own website and<br>
>> > find<br> >> > some way to export the book to be imported into Drupal.org. I could have<br> >> > access to the top level pages. I could do something during DrupalCon.<br> >> ><br> >> > I am open to suggestions. Thanks!<br>
>> > Sameer.<br> >> ><br> >> ><br> >><br> >> > --<br> >> > Pending work: <a href="http://drupal.org/project/issues/documentation/">http://drupal.org/project/issues/documentation/</a><br>
>> > List archives: <a href="http://lists.drupal.org/pipermail/documentation/">http://lists.drupal.org/pipermail/documentation/</a><br> >> ><br> >> --<br> >> Pending work: <a href="http://drupal.org/project/issues/documentation/">http://drupal.org/project/issues/documentation/</a><br>
>> List archives: <a href="http://lists.drupal.org/pipermail/documentation/">http://lists.drupal.org/pipermail/documentation/</a><br> ><br> ><br> > --<br> > Pending work: <a href="http://drupal.org/project/issues/documentation/">http://drupal.org/project/issues/documentation/</a><br>
> List archives: <a href="http://lists.drupal.org/pipermail/documentation/">http://lists.drupal.org/pipermail/documentation/</a><br> ><br> --<br> Pending work: <a href="http://drupal.org/project/issues/documentation/">http://drupal.org/project/issues/documentation/</a><br>
List archives: <a href="http://lists.drupal.org/pipermail/documentation/">http://lists.drupal.org/pipermail/documentation/</a><br> </blockquote></div><br>