> In that case, I suggest to put as much as possible (i.e. everything not > _really_ technical) on the wiki. Since harder updates (finding the > files, syntax, no live feedback) will sum up with lazyness to prevent > sphinx changes.
"For besides other considerations, everybody is more inclined to neglect the duty which he expects another to fulfill; as in families many attendants are often less useful than a few. Each citizen will have a thousand sons who will not be his sons individually but anybody will be equally the son of anybody, and will therefore be neglected by all alike." (Aristotle, Politics II, 3) I would prefere put everything into sphinx for that reason (so far, it has not been the case that people edit wiki because it is easier; there were almost no edits at all, excapt everybody his/her page of interest). Sphinx has several benefits which the wiki doesn't, among which: * live yade sessions (i.e. the output in Out [43]: is really generated by yade as the documentation is processed, not copy&pasted, therefore always up to date) * xrefs to yade classes/functions * sphinx docs are packaged and can be browsed offline (file:///usr/share/doc/yade-0.50/html/index.html if you have lucid's yade-0.50-doc installed) * you can easily type math in those docs. > Ok, why not. The only thing I'm wondering is if first-time visitors will > not loose themselves in reference manuals before checking the wiki. That is just a matter of designing the title page clearly. Currently, it is not very well structured, but there is nolimits to your fantasy in this respect, it is a pure HTML (doc/sphinx/templates/index.html FYI). I think newcomers don't care what is wiki and what is sphinx, but they want to know what they want to know. > (btw, I didn't find any wiki in your links, bad examples?). from https://yade-dem.org/sphinx/ , second paragraph: "Yade is located at www.yade-dem.org, which contains this documentation and wiki." ("wiki" is a hyperlink) Whatever are those nice ideas about documentation, someone has to implement them. Cheers, v. _______________________________________________ Mailing list: https://launchpad.net/~yade-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~yade-dev More help : https://help.launchpad.net/ListHelp
