Vanilla library documentation: need opinions.

mattucf

I've written documentation for the People::RoleManager class, and I'd like some opinions before I continue.

Does the formatting look OK?
Too much or too little structure?
Too much or too little detail?

Stash

Nice, just a little too much white space IMO. I'd close of the gap between the headings and the horizontal lines and also between the "Signature:" and "Description:" and the paragraph below

ithcy

^^exactly

WallPhone

Looks great!
I would suggest using the ObjectFactory in the constructor reference, since that is the best practice to use when constructing an object in Vanilla:$RoleManager = $Context->ObjectFactory->NewContextObject($Context, 'RoleManager');

mattucf

Is there any way to do that (eliminate whitespace) with the wiki syntax? The heading blocks are adding a blank line beneath them even if I position the text (or horizontal rules) directly underneath.

@Wallphone: good point. Fixed.

Grahack

I think that it's great like that. Space around heading titles is a good point for readability.

Well if you want my deepest thought of the day, I think that the ---- are not welcome because:
1) it takes time to type them
2) if I want to contribute, I prefer the wiki source to be simple, not starting to think: "did he code this the same way? well, I have to check"
3) on FF & XP, the TOC messes the line lenght

About the white space (wa, two deep thoughts), it could be corrected through the doku css. When you think you have the simplest and the most efficient way to edit the docs, Mark will maybe have some time to upload a new .css that we could have written.

The simpler, the better + css.

We have to remember: the number of pages to produce is HUGE, and hard to maintain in the long term.