Improve the documentation please

What it says on the tin: a place to discuss proposed new features.
Post Reply
paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Improve the documentation please

Post by paul424 » Fri Nov 22, 2013 12:04 am

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 .
0 x

Transporter
Minaton
Posts: 933
Joined: Mon Mar 05, 2012 11:37 am
Location: Germany

Re: Improve the documentation please

Post by Transporter » Fri Nov 22, 2013 8:44 am

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
0 x

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Fri Nov 22, 2013 11:45 am

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 ...
0 x

User avatar
c6burns
Beholder
Posts: 1511
Joined: Fri Feb 22, 2013 4:44 am
Location: Deep behind enemy lines

Re: Improve the documentation please

Post by c6burns » Fri Nov 22, 2013 12:15 pm

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.
0 x

User avatar
Zonder
Gargoyle
Posts: 1081
Joined: Mon Aug 04, 2008 7:51 pm
Location: Manchester - England
x 3

Re: Improve the documentation please

Post by Zonder » Fri Nov 22, 2013 2:45 pm

c6burns wrote:I'd say Confluence is miles ahead of mediawiki for software projects.
I have to agree.
0 x
There are 10 types of people in the world: Those who understand binary, and those who don't...
My Blog - http://www.This post is suspected as SPAM! If you feel otherwise contact a moderator.

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Fri Nov 22, 2013 5:40 pm

>> 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 .
0 x

User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
Contact:

Re: Improve the documentation please

Post by Klaim » Fri Nov 22, 2013 6:28 pm

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).
0 x

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Fri Nov 22, 2013 8:37 pm

Excuse me , I wanted to create a separate encyclopeida wiki for that purpose .
0 x

User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
Contact:

Re: Improve the documentation please

Post by Klaim » Fri Nov 22, 2013 10:12 pm

Do you mean you want to have another wiki along with the current one? What would be the use of the second one?
0 x

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Fri Nov 22, 2013 10:42 pm

Providing encyclopedic entries of Ogre terms , classes , programming concepts etc.
0 x

User avatar
c6burns
Beholder
Posts: 1511
Joined: Fri Feb 22, 2013 4:44 am
Location: Deep behind enemy lines

Re: Improve the documentation please

Post by c6burns » Fri Nov 22, 2013 11:04 pm

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.
0 x

User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
Contact:

Re: Improve the documentation please

Post by Klaim » Fri Nov 22, 2013 11:06 pm

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?
0 x

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Fri Nov 22, 2013 11:12 pm

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 !
0 x

Transporter
Minaton
Posts: 933
Joined: Mon Mar 05, 2012 11:37 am
Location: Germany

Re: Improve the documentation please

Post by Transporter » Sat Nov 23, 2013 9:23 am

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.
0 x

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Sat Nov 23, 2013 10:18 pm

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 ?
0 x

User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
Contact:

Re: Improve the documentation please

Post by Klaim » Sat Nov 23, 2013 10:31 pm

Nothing prevents you to create one and see if it works.
0 x

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Sun Nov 24, 2013 7:00 pm

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. ?
0 x

PhilipLB
Google Summer of Code Student
Google Summer of Code Student
Posts: 550
Joined: Thu Jun 04, 2009 5:07 pm
Location: Berlin

Re: Improve the documentation please

Post by PhilipLB » Sun Nov 24, 2013 8:53 pm

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
0 x
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: 505
Joined: Mon Apr 02, 2007 12:18 am
Location: Sweden

Re: Improve the documentation please

Post by lingfors » Sun Nov 24, 2013 8:54 pm

Seriously... Why is one Wiki not enough? Anyone can edit it, and write anything they want.
0 x

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Sun Nov 24, 2013 9:07 pm

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 ! "
0 x

Transporter
Minaton
Posts: 933
Joined: Mon Mar 05, 2012 11:37 am
Location: Germany

Re: Improve the documentation please

Post by Transporter » Sun Nov 24, 2013 9:33 pm

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.
0 x

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Mon Dec 02, 2013 11:32 pm

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.
0 x

User avatar
shadowfeign
Goblin
Posts: 213
Joined: Mon Jan 26, 2009 11:51 pm

Re: Improve the documentation please

Post by shadowfeign » Tue Dec 03, 2013 12:23 am

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?
0 x

paul424
Gremlin
Posts: 196
Joined: Thu May 24, 2012 7:16 pm
x 1

Re: Improve the documentation please

Post by paul424 » Tue Dec 03, 2013 12:28 am

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

Post Reply