Crystal Space
Welcome, Guest. Please login or register.
November 27, 2014, 02:35:03 pm

Login with username, password and session length
Search:     Advanced search
9026 Posts in 2046 Topics by 9146 Members
Latest Member: Olavinka
* Home Help Search Login Register
+  Crystal Space
|-+  Miscellaneous
| |-+  Article/Tutorial Requests
| | |-+  Changing the API documentation to a wiki
« previous next »
Pages: [1] Print
Author Topic: Changing the API documentation to a wiki  (Read 5508 times)
Jelkimantis
Newbie
*
Posts: 4


View Profile Email
« on: October 13, 2008, 06:24:26 pm »

Can we change the API documentation into a wiki format that includes examples? 

I'm contemplating something similar to the PHP documentation where there are examples given in the API page and then you can log in and comment on the examples and give specific examples to a variety of problems.

This might decrease the number of "how do I use..." questions in the forums.

jsl
Logged
jorrit
Administrator
Hero Member
*****
Posts: 1706


View Profile
« Reply #1 on: October 13, 2008, 08:06:02 pm »

The api manual is automatically generated from the source (daily). It is hard to make that a wiki. However, we used to have a comment system in the past so that you could add comments to every generated page. The cronjob that generated the documentation would make sure the comments were not discarded. We had to stop this comment system because it was misused for spam purposes.

Greetings,
Logged
Jelkimantis
Newbie
*
Posts: 4


View Profile Email
« Reply #2 on: October 13, 2008, 11:37:09 pm »

Wow.  That's quite a neat bit of code, pulling the API from source.  Would it be feasible to develop a secondary documentation forum?  I hate to beleaguer the point, but I really want it.

Would it be appropriate to start such a section in the already existing wiki, essentially using the API tree as a starting point and putting in some code with explanations of what the code snippet does?

I know that my knowledge is limited in this respect, but as I gain knowledge I could increase my contribution, and others could contribute as well. 

So, the question stands, would it be appropriate to start building an explanation wiki of the API tree?  Or does the API tree change too dynamically to allow this type of endeavor?

jsl
Logged
Vincent
Full Member
***
Posts: 191


View Profile WWW
« Reply #3 on: November 24, 2008, 07:27:40 pm »

I think that topic was discussed in the past already, and the weak point of the wiki is keeping it up-to-date.
Even without API, some of the tutorials on the actual wiki are sometimes quite outdated,
and/or the CS version they cover is not even mentioned, thus leading to confusion.
Maybe some automation could be done, but I'm not sure anyone has time for that.
But the point remains, more examples, and more practictal ones, would be good...
Logged
Pages: [1] Print 
« previous next »
Jump to:  

Powered by MySQL Powered by PHP Powered by SMF 1.1.2 | SMF © 2006-2007, Simple Machines LLC Valid XHTML 1.0! Valid CSS!
Page created in 5.509 seconds with 18 queries.