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.