Talk:Manual

From ODE Wiki

How to improve overall readability?

1) Should we put each API function/struct etc. on a seperate page?

• this fits the Wiki way of doing things, i.e. lots of links
• other Wikis/offline documentation I've seen do this too, it seems to work
• results in smaller pages, easier to editors, easier for readers to spot changes
• may make it a bit harder to find relevant information (though see note #3)

2) Turn each API function name, struct/type definition (with exception of sample code of cource) into a link to each description page respectively.

3) I think we should put "See Also" links at the bottom of page, for example to similar functions or anything else directly relevant.

4) Put a "Next" and "Previous" link at the bottom of each page, so you can still browse it like a regular manual (this would be usefull for people new to ODE). Personally I'm not in favor of this, since if such links are erroneously omitted, in wrong order etc. readers may unknowingly skip entire sections or end up in an infinite loop. ;-) New pages would not be picked up either, if these links are omitted.

5) ...

Perhaps we should pick a single page of the manual, and just experiment with it. Once settled with a style that we like we can apply it to other pages.

All feedback is welcome.

-Martijn

Response: We've decided to do the "programmer's guide" part of the manual in WIKI, but the "reference guide" part (API) will be generated from inline comments in source code, using doxygen. See ode/doc in SVN repo.

-Bram