What is the best way to expose the Open Documentation?

conviojames

We are brainstorming on the best way to document the APIs and Extensions, and we also wnat to know what is the best way to expose the documentation. I need your feedback to help guide our next moves.

Setting aside the quality of the documentation itself for a moment, let's focus solely on the delivery.

• Does the current documentation site make it easy for you to browse the documentation?
• Does the current documentation site present the technical aspects in a useful manner?
• Would the document capabilities of this community work better than the current documentation site?
• Would you prefer a true wiki presentation of the documentation?
• What features are must haves for a documentation site to be useful to you?
• What features are nice to have for a documentation site to be useful to you?
• What is your favorite documentation site out there on the web?

mark.ajws

IMHO, try and emulate jQuery's documentation as much as possible.

http://docs.jquery.com/

Matt Burghdoff 2

I think what would really make the API documentation in particular valuable beyond compare is a walk-through of setting a page up, step by step. That's how I learned PHP, by walking through samples and setting up a web database by writing out the code manually with a "guide" to tell me what I was supposed to be doing and why the pieces were going in at this point. I'm trying to learn the Convio API by looking at the code of other organizations which have successfully implemented and adapting the code.

Adrian Cotter

*It is fairly easy to browse the documentation

*I'm finding it a little difficult to separate the idea of presentation v content. I think there is an opaqueness to the documentation as it is (esp. around server-side versus client-side)

*I think you need a fairly static site to display this information. But it would be good if one could attach the discussions to the particulars of the API -- create and feed particular discussions onto particular pages?

*I'm dubious that a WIKI would be of much value here, unless it just makes it easier for you all to edit

*Maybe some language independent example of how to do various things... to illustrate the various things you have to do in order to use parts of the API

*Nice to haves would be specific language examples

My favorite documentation site out there is - nice blend of static info with discussion at the bottom with more examples.

http://www.php.net

In terms of APIs, I've found Prototype's API documentation easy to dive into

http://www.prototypejs.org/api