Page 1 of 1

Improve the documentation please

Posted: Fri Nov 22, 2013 12:04 am
by paul424
I have mine ideas of improving Ogre's documentation :

1) First start a true wiki of Ogre terms ( ogre lexicons can be good starter lists ) ANYONE in here can edit .

2) Improve this : http://www.ogre3d.org/tikiwiki/tiki-ind ... chitecture . Schemes In Computer Science are SOOOO GREAT especially when you don't use English natively so you don't have to translate all those sophisticated phrases when building mental model of what actually given API set does and works . Two pictures is too Little !!!!!
I would select a few OGre3d subsystems like Memory Animation General Resources Materials Math Effects Overlays Scene Image RenderSystem LOD RTShader and run an UML reverse engineer code , which does CODE -> UML SCHEMAS , example like this : http://www.visual-paradigm.com/ .

3) Your manual is too short , probably everyone knows it so no sense on bubbling on this >_> ...


cheers .

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 8:44 am
by Transporter
1) There is a wiki http://www.ogre3d.org/wiki/. Anyone with a forum account can edit it.

2) The page must be completely rewritten for the release of Ogre 2.

3) See http://www.ogre3d.org/forums/viewtopic.php?f=4&t=78545

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 11:45 am
by paul424
No , you don't get me at all. That site is really powered by some wiki-like CMS, but I suggested the true wiki, with the encyclopedic way of sorting content by one topic entry and encyclopedic exact ( Like with orginal jimmy Walles www.wikipedia.org ) ! So what I wanted is I search >>culling<< and I get similar entry as on wikipedia , except it discuss how the OGRE does it , how I can use it, example codes etc. Instaed I get mixture-salad of every page containing that word http://www.ogre3d.org/tikiwiki/tiki-sea ... &search=Go . I might start a small Wiki project like this ( using Ogre3d Lexicon as a start ) under assumption that it would be linked from here ...

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 12:15 pm
by c6burns
By "true wiki" I guess you mean mediawiki, which is really just one implementation of the wiki concept.

Personally, I'd rather have the Ogre team focus on code and have the community rally behind and play catchup with documentation. This is what I'm used to from an open source project. And if an infrastructure switch were to be considered, which I don't think is necessary, I'd say Confluence is miles ahead of mediawiki for software projects.

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 2:45 pm
by Zonder
c6burns wrote:I'd say Confluence is miles ahead of mediawiki for software projects.
I have to agree.

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 5:40 pm
by paul424
>> I'd say Confluence is miles ahead of mediawiki for software projects. <<
Pardon, my English bad , what does confluence ( of community and users ? ) has to do with mine idea of mediawiki .

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 6:28 pm
by Klaim
paul424 wrote:>> I'd say Confluence is miles ahead of mediawiki for software projects. <<
Pardon, my English bad , what does confluence ( of community and users ? ) has to do with mine idea of mediawiki .
Confluence is a wiki engine too, but designed for software development.

Anyway, personally I wouldn't change the wiki engine right now (except if it was easy and not time consuming).

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 8:37 pm
by paul424
Excuse me , I wanted to create a separate encyclopeida wiki for that purpose .

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 10:12 pm
by Klaim
Do you mean you want to have another wiki along with the current one? What would be the use of the second one?

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 10:42 pm
by paul424
Providing encyclopedic entries of Ogre terms , classes , programming concepts etc.

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 11:04 pm
by c6burns
Since encyclopedic basically means "comprehensive", I see no reason you can't help contribute to bring the current wiki closer to that definition without any change to its infrastructure. Unless your definition of encyclopedic means "like wikipedia in that it uses mediawiki infrastructure" in which case I feel the proposal is doomed to meet with disapproval.

I feel like your problem with the wiki is content related, but you are *saying* it's infrastructure related.

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 11:06 pm
by Klaim
paul424 wrote:Providing encyclopedic entries of Ogre terms , classes , programming concepts etc.
Most programming concepts are just graphic hardware concepts, so you should first be familiar with that (and C++ obviously).
Doesn't the API documentation helps with terms and classes?

Re: Improve the documentation please

Posted: Fri Nov 22, 2013 11:12 pm
by paul424
Kali : APi documentation has no hyperlinks , it's short , it does not contain any minimal code examples , schemes etc. etc.
Plus it does not appear immidiatly, but you have to unreaveal this bloody >>more << button .

Hmm imagine a fresh person going to study Computer Graphics , and come across small encylopedia , which combines articles with small examples using real , graphical engine in C/C++ ! Who would like to have such intro into 3D computer graphics, if you haven't know the topic already ? I would love for sure ! And would be willing to study more advanced topics with it !

Re: Improve the documentation please

Posted: Sat Nov 23, 2013 9:23 am
by Transporter
paul424 wrote:Kali : APi documentation has no hyperlinks , it's short , it does not contain any minimal code examples , schemes etc. etc.
Plus it does not appear immidiatly, but you have to unreaveal this bloody >>more << button .
I don't know which API doc are you using, but my doxygen doc has a lot of links.

Re: Improve the documentation please

Posted: Sat Nov 23, 2013 10:18 pm
by paul424
Donno why do you abort a good idea from a start ? What would happen if new people woudl have additional source of OGRE information/ documentation ?
Can you make a small survey of how many people would support such wiki media project ( that is editing etc. ) if there was one ?

Re: Improve the documentation please

Posted: Sat Nov 23, 2013 10:31 pm
by Klaim
Nothing prevents you to create one and see if it works.

Re: Improve the documentation please

Posted: Sun Nov 24, 2013 7:00 pm
by paul424
Sure, but if there are no links to it from that site no one know it exist == it dies at the beginning.
So if I start a wikimedia service you would link it from here, right , along with Forum Rules , ogre3d, Addons F. , Wiki etc. ?

Re: Improve the documentation please

Posted: Sun Nov 24, 2013 8:53 pm
by PhilipLB
I don't get why to setup a second wiki for that, too. :)

What about this? This seems similar to what you are requesting: http://www.ogre3d.org/tikiwiki/tiki-ind ... re+Lexicon

Re: Improve the documentation please

Posted: Sun Nov 24, 2013 8:54 pm
by lingfors
Seriously... Why is one Wiki not enough? Anyone can edit it, and write anything they want.

Re: Improve the documentation please

Posted: Sun Nov 24, 2013 9:07 pm
by paul424
If IT companies were like toaster producers,
IBM Toasters:
"We want one, two, three big toasters per continent where people bring bread to be submitted for overnight toasting. That makes a worldwide market for twelve, maybe sixteen toasters. Who does eat toasts , anyway ? Wait ... what millions of people everyday ? Kill our marketing specialists ! "

Re: Improve the documentation please

Posted: Sun Nov 24, 2013 9:33 pm
by Transporter
paul424 wrote:Sure, but if there are no links to it from that site no one know it exist == it dies at the beginning.
So if I start a wikimedia service you would link it from here, right , along with Forum Rules , ogre3d, Addons F. , Wiki etc. ?
Feel free to create your own wiki. I'm sure it's possible to set a link on it. But I think you have to create the content by yourself. I won't add content to your wiki, because I think the main wiki is enough.

Re: Improve the documentation please

Posted: Mon Dec 02, 2013 11:32 pm
by paul424
http://www.ogre3d.org/tikiwiki/img/wiki ... eFrame.png
So who could improve that , Should I consider it as vaild graph of rendering loop in Ogre3d ?

I really would like to see the Ogre rendering pipe scheme, some SceneManager API methods are criptic to me .

Re: Improve the documentation please

Posted: Tue Dec 03, 2013 12:23 am
by shadowfeign
paul424 wrote:If IT companies were like toaster producers,
IBM Toasters:
"We want one, two, three big toasters per continent where people bring bread to be submitted for overnight toasting. That makes a worldwide market for twelve, maybe sixteen toasters. Who does eat toasts , anyway ? Wait ... what millions of people everyday ? Kill our marketing specialists ! "
wait, you're saying you want to have to search millions of toasters in the morning to find where your toast is?

Re: Improve the documentation please

Posted: Tue Dec 03, 2013 12:28 am
by paul424
In this old joke Toaster == Computer. Probably allusion to non-interest of IBM in personal computers till the PC standard .