Improve the documentation please

What it says on the tin: a place to discuss proposed new features.
Post Reply
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Improve the documentation please

Post 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 .
Transporter
Minaton
Posts: 933
Joined: Mon Mar 05, 2012 11:37 am
Location: Germany
x 110

Re: Improve the documentation please

Post 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
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post 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 ...
User avatar
c6burns
Beholder
Posts: 1512
Joined: Fri Feb 22, 2013 4:44 am
Location: Deep behind enemy lines
x 138

Re: Improve the documentation please

Post 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.
User avatar
Zonder
Ogre Magi
Posts: 1168
Joined: Mon Aug 04, 2008 7:51 pm
Location: Manchester - England
x 73

Re: Improve the documentation please

Post by Zonder »

c6burns wrote:I'd say Confluence is miles ahead of mediawiki for software projects.
I have to agree.
There are 10 types of people in the world: Those who understand binary, and those who don't...
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post 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 .
User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
x 56
Contact:

Re: Improve the documentation please

Post 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).
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post by paul424 »

Excuse me , I wanted to create a separate encyclopeida wiki for that purpose .
User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
x 56
Contact:

Re: Improve the documentation please

Post 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?
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post by paul424 »

Providing encyclopedic entries of Ogre terms , classes , programming concepts etc.
User avatar
c6burns
Beholder
Posts: 1512
Joined: Fri Feb 22, 2013 4:44 am
Location: Deep behind enemy lines
x 138

Re: Improve the documentation please

Post 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.
User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
x 56
Contact:

Re: Improve the documentation please

Post 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?
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post 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 !
Transporter
Minaton
Posts: 933
Joined: Mon Mar 05, 2012 11:37 am
Location: Germany
x 110

Re: Improve the documentation please

Post 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.
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post 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 ?
User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
x 56
Contact:

Re: Improve the documentation please

Post by Klaim »

Nothing prevents you to create one and see if it works.
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post 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. ?
PhilipLB
Google Summer of Code Student
Google Summer of Code Student
Posts: 550
Joined: Thu Jun 04, 2009 5:07 pm
Location: Berlin
x 108

Re: Improve the documentation please

Post 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
Google Summer of Code 2012 Student
Topic: "Volume Rendering with LOD aimed at terrain"
Project links: Project thread, WIKI page, Code fork for the project
Mentor: Mattan Furst


Volume GFX, accepting donations.
User avatar
lingfors
Hobgoblin
Posts: 525
Joined: Mon Apr 02, 2007 12:18 am
Location: Sweden
x 79

Re: Improve the documentation please

Post by lingfors »

Seriously... Why is one Wiki not enough? Anyone can edit it, and write anything they want.
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post 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 ! "
Transporter
Minaton
Posts: 933
Joined: Mon Mar 05, 2012 11:37 am
Location: Germany
x 110

Re: Improve the documentation please

Post 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.
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post 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 .
Last edited by paul424 on Tue Dec 03, 2013 12:26 am, edited 1 time in total.
User avatar
shadowfeign
Goblin
Posts: 213
Joined: Mon Jan 26, 2009 11:51 pm
x 15

Re: Improve the documentation please

Post 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?
User avatar
paul424
Gnome
Posts: 314
Joined: Thu May 24, 2012 7:16 pm
x 13

Re: Improve the documentation please

Post by paul424 »

In this old joke Toaster == Computer. Probably allusion to non-interest of IBM in personal computers till the PC standard .
Post Reply