Yeah one improvement may be to place the API "hurl" tool into each API documentation page with all parameter pre-filled so it is ready to be experiment with to see how the responses look. This also helps avoid out of date info if the responses should change.
Josh On Tue, Apr 27, 2010 at 4:21 PM, Taylor Singletary < taylorsinglet...@twitter.com> wrote: > Thanks for the feedback, Jonathon. We're working to address all these pain > points on an ongoing basis. > > Taylor Singletary > Developer Advocate, Twitter > http://twitter.com/episod > > > On Tue, Apr 27, 2010 at 2:17 PM, Jonathon Hill <jhill9...@gmail.com>wrote: > >> The new dev.twitter.com website that launched at Chirp a few weeks ago >> is very nice and attractive but there are several major usability >> issues: >> >> * The new API documentation does not provide return values of the API >> calls. The old wiki provided this information, along with usage notes >> that are not present either on the new site. >> >> * It is difficult to look up API endpoints required for a given type >> of functionality. If you don't remember the exact endpoint to look >> for, it can be frustrating trying to find the right one. This would >> easily be fixed using a more descriptive list of endpoints, and/or >> more visual contrast between headings and list items. >> >> * I tend to overlook the endpoint description in the blue header >> section. My eyes expect it in the white area below. Please move it, >> and make it stand out more. >> >> * The Supported formats, Supported request methods, Requires >> Authentication, and Rate Limited sections use up an awful lot of >> vertical space on the page unnecessarily. Making each one of these a >> heading also dilutes the visual hierarchy on the page and takes away >> from more detailed and important information on the page, from a >> reference standpoint. I think these would be more effectively >> presented as a list under a "Metadata" heading, or as a small table. >> >> * The API console is very restricted without login and registration of >> an app. I think this is a mistake. Login should be required only for >> those calls that require authentication. >> >> * The API console would be much easier to use if there were parameter >> hints for each call on the page somewhere. Prepopulating the parameter >> list would be awesome! >> >> These are all things that have been kindof in my face as I've tried to >> use dev.twitter.com in my day to day development work. I would be >> delighted if you would address these issues. >> >> Thanks! >> >> Jonathon Hill >> Company52 >> http://company52.com >> @compwright >> > >