Posted by rfay on November 25, 2009 at 10:03pm
4 followers
Jump to:
| Project: | Documentation |
| Component: | Placement and navigation |
| Category: | task |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed (fixed) |
Issue Summary
There are currently 3 "orphaned" documents in CVS in contributions/docs/developer/topics.
Forms API
Forms API Reference
Javascript startup
I propose that we move all 3 into the handbook where there's more likely to be maintained.
Any objections?
Comments
#1
The Forms API Reference is really an API document that belongs on api.drupal.org. I realize it is never maintained there, but it does belong with the code. I actually think it should be moved into core rather than the handbook.
#2
I agree that forms API doc is logically a core piece. However it's such a complicated piece of HTML it would be nearly impossible to maintain as PHPDoc. I do agree with you on where it logically belongs. However, as a matter of practicality I still propose moving it into the handbook where it can be maintained more easily.
Do you have any objections on the other two docs? They *definitely* should move to the handbook IMO.
#3
No objection whatsoever to the other two.
#4
I'll move the forms API intro. It needs some work. I may do a bit of work on it first.
Where should the Forms API intro doc land in the handbook? And how do we handle the multiple versions of it? MENU_LOCAL_TASK? How is this done in the handbook?
Thanks,
-Randy
#5
There's an API section of the Handbook. Form API sub-section of that is at: http://drupal.org/node/37775
Mutliple Drupal version applicability: We don't have a good way to handle that in the Handbook at this time (have been debating this for new doc AI, which is stalled until add1sun gets back into action, as far as I know). There is no way to do MENU_LOCAL_TASK in the Handbook either. All you can do is make a landing page, and then have child pages for each Drupal version. Or if the changes are minor, just make a page that applies to several versions and note the minor differences.
#6
And if you are messing with the Form API on-line section, you might also take a look at #53819: Forms API #validation outdated..
#7
#53819: Forms API #validation outdated. appears to be something else entirely. I am making minor changes to the Form API doc in the Topics section of contrib/developer/docs.
Thanks for the pointers on the handbook page. Just took a look there and it's an utter catastrophe. I guess I'll move stuff there and then try to clean up and then cry help.
#8
+1 for moving these
#9
See also #100680: Automatically generate Forms API & other big array documentation. Not much progress there, but there are a few ideas.
#10
#9/@drumm: I totally agree that the API doc for forms API needs to be somehow embedded into the code so it can be maintained with the code, rather than in this ad-hoc doc that someone sometimes decides to update when they notice it's not in synch with the code.... So that is good news that people are thinking about it!
Anyway, given that rfay, it's another reason to leave the FAPI reference as-is for the moment and just move those other two docs.
#11
I don't actually see how it's a reason to leave the FAPI as is... I'd certainly like to see better techniques in the future, but don't see how that's related to where the FAPI doc lives right now.
Don't assume that I'm arguing all that hard. But now it's 2 to 1 of interested parties :-) @jhodgdon has the upper hand still anyway, though, IMO, being the de-facto curator of these docs.
#12
#100680: Automatically generate Forms API & other big array documentation is not anywhere near implementation. It is still a research project. There aren't any clearly good solutions and my personal time for API module is dedicated to more-solvable problems. Don't count on that unless you know (or are) someone with a clearly good idea and time to build it.
It is okay to leave some HTML docs as-is for awhile.
#13
When the quick start form guide is moved into drupal.org:
#719306: Documentation improvement in Forms API Quickstart Guide
#14
I just chatted with katbailey about the Javascript Startup, and IMO it should just be removed (for D7 at least) and anything that refers to it should refer instead to http://drupal.org/node/205296.
#15
Sounds like a good idea to me. I don't know of anything referring to it on api.drupal.org.
#16
Committed: http://drupal.org/cvs?commit=345756
Moved the Form API quickstart to http://drupal.org/node/751826
#17
Yay!!!
#18
I should set up redirect in .htaccess for these. Please post old URLs and where they should go.
#19
Thanks, @drumm:
The D7 Form API quickstart (formerly http://api.drupal.org/api/drupal/developer--topics--forms_api.html/7) is now http://drupal.org/node/751826.
The former D7 Javascript Startup Guide: http://api.drupal.org/api/drupal/developer--topics--javascript_startup_g... is not going to exist as is, but could be pointed to http://drupal.org/node/751744.
#20
Redirects added
#21
Automatically closed -- issue fixed for 2 weeks with no activity.