User:Sumanah/ApiDocsImprovement

Ben Lobaugh wrote this proposal, which other people should now feel free to go ahead and implement (slight editing by Sumana):

In a nutshell, at the SanFran Wikipedia Hackathon Roan gave a tutorial on using the Wikipedia API. Roan did a great job, however what was painfully obvious was that the API documentation and such is just not up to par yet to make developers excited about using. While I was working at Microsoft a major part of my responsibilities was to create training programs for presentation and print, along with developing technical documentation and samples.

Let me toss out what I would like to see accomplished and we can debate over it until it is something good:

• Create an API documentation portal that contains information/samples/sandbox for users that is easy to use and understand. Some examples Sumana and I talked about at the hackathon are docs from Flickr, Meetup, and Etsy
• Develop a flow for API tutorials, along with a basic set containing common API usages. This set of tutorials can then be expanded by the community and on request
• Develop a set of training materials that can be used at conferences and hackathons. What I have noticed in my travels is that developers tend to enjoy getting their hands dirty with the code rather than, and in addition to, listening to a lecture for an entire session. The goal here would be to create presentations for use on a big stage that would be just talk, and presentations that can be taken to events, such as hackathons, to get developers into the code and having something working right away

...Max, you should continue to own that, I just want to help improve the experience for current and incoming developers.

Here is what [we need] to do:

• build a documentation strategy
• build a console strategy (i.e. the sandbox)
• create presentations
• create content for labs
• visual design. I am definitely not a designer. If Brandon & Heather would be willing to take the content and build the layout that would be awesome
• code the sandbox

How do you all feel about that? If everyone likes it let's start looking at other API docs to see what we like/dislike and build up the strategy for displaying it, and Roan [and others] can also start on some of the intro to the API presentations.