The state of Ogre's documentation

Discussion area about developing or extending OGRE, adding plugins for it or building applications on it. No newbie questions please, use the Help forum for that.
Oogst
OGRE Expert User
OGRE Expert User
Posts: 1067
Joined: Mon Mar 29, 2004 8:49 pm
Location: the Netherlands
x 43
Contact:

Re: The state of Ogre's documentation

Post by Oogst »

Sounds good! I'd be happy to help updating the tutorials. :)
My dev blog
Awesomenauts: platforming MOBA (PC/Mac/Linux/XBox360/X1/PS3/PS4)
Blightbound: coop online dungeon crawler (PC)
Swords & Soldiers: side-scrolling RTS (Switch/PS3/Wii/PC/Mac/Linux/iPhone/iPad/Android)
Proun: abstract racing game (PC)
Cello Fortress: mixing game and live cello performance
The Ageless Gate: cello album
User avatar
spacegaier
OGRE Team Member
OGRE Team Member
Posts: 4304
Joined: Mon Feb 04, 2008 2:02 pm
Location: Germany
x 135
Contact:

Re: The state of Ogre's documentation

Post by spacegaier »

Yes, I think besides the component documentation, up-to-date tutorials are the second major part since that is the first contact with Ogre usually. So they need to be current.
Ogre Admin [Admin, Dev, PR, Finance, Wiki, etc.] | BasicOgreFramework | AdvancedOgreFramework
Don't know what to do in your spare time? Help the Ogre wiki grow! Or squash a bug...
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: The state of Ogre's documentation

Post by PhilipLB »

Where will the component documentation be placed? Wiki or manual?
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.
al2950
OGRE Expert User
OGRE Expert User
Posts: 1227
Joined: Thu Dec 11, 2008 7:56 pm
Location: Bristol, UK
x 157

Re: The state of Ogre's documentation

Post by al2950 »

PhilipLB wrote:Where will the component documentation be placed? Wiki or manual?
Interesting question, as I previously said I started creating component tutorials on the wiki, http://www.ogre3d.org/tikiwiki/tiki-ind ... =Tutorials, well atleast a structure!

I only tend to use the manual as a reference for the various scripts in Ogre.
User avatar
dark_sylinc
OGRE Team Member
OGRE Team Member
Posts: 5296
Joined: Sat Jul 21, 2007 4:55 pm
Location: Buenos Aires, Argentina
x 1278
Contact:

Re: The state of Ogre's documentation

Post by dark_sylinc »

I've got a question to ask:

How and where will the new documentation format be written (I'm talking about the official one)?

More simply put, my experience with Tikiwiki's wysiwyg editor has been awful. I love the current manual format, but LaTex editing is not the best.

A tweet a weeks backs suggested a wiki edited by ogre devs only seems like a good idea. I'm slightly inclined to wikibooks format.
Collaborative work is important. But I also need it to be able for download for an "offline mode", which is also very important.

Another method I'm keen with is ODF documents. They're great. Unlike Office, OpenOffice has a "object oriented" way of thinking, where one predefines a few formats (just like html's CSS: header 1, 2, 3, parragraphs, etc) and then control the format of the whole document in a centralized place.
AFAIK ODFs are subversioning-friendly (odf is just a zipped file consisting of xml files). And apparently there's an Hg extension for them, but I don't know how well it works (particularly with conflicts).

Another option is Google Docs, which is very powerful and easy to use.
User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
x 56
Contact:

Re: The state of Ogre's documentation

Post by Klaim »

dark_sylinc wrote:I've got a question to ask:

How and where will the new documentation format be written (I'm talking about the official one)?

More simply put, my experience with Tikiwiki's wysiwyg editor has been awful. I love the current manual format, but LaTex editing is not the best.

A tweet a weeks backs suggested a wiki edited by ogre devs only seems like a good idea. I'm slightly inclined to wikibooks format.
Collaborative work is important. But I also need it to be able for download for an "offline mode", which is also very important.

Another method I'm keen with is ODF documents. They're great. Unlike Office, OpenOffice has a "object oriented" way of thinking, where one predefines a few formats (just like html's CSS: header 1, 2, 3, parragraphs, etc) and then control the format of the whole document in a centralized place.
AFAIK ODFs are subversioning-friendly (odf is just a zipped file consisting of xml files). And apparently there's an Hg extension for them, but I don't know how well it works (particularly with conflicts).

Another option is Google Docs, which is very powerful and easy to use.
If you want to go this way, then don't forget also the currently very popular MarkDown (which is apparently usable by Doxigen).
I prefer AsciiDoc myself because it allows more precise formatting. Both can generate different types of document from HTML to pdf to word or other document formats.
I wouldn't go with Google Doc or anything similar for this kind of technical documentation.
User avatar
Mikachu
Gnoll
Posts: 603
Joined: Thu Jul 28, 2005 4:11 pm
Location: Nice, France
x 35

Re: The state of Ogre's documentation

Post by Mikachu »

Klaim wrote:If you want to go this way, then don't forget also the currently very popular MarkDown (which is apparently usable by Doxigen).
The fact that doxygen now supports it is a big win in terms of workflow simplicity, and one of the reasons why I switched to it for OgreProcedural manual...
OgreProcedural - Procedural Geometry for Ogre3D
Transporter
Minaton
Posts: 933
Joined: Mon Mar 05, 2012 11:37 am
Location: Germany
x 110

Re: The state of Ogre's documentation

Post by Transporter »

Mikachu wrote:The fact that doxygen now supports it is a big win in terms of workflow simplicity, and one of the reasons why I switched to it for OgreProcedural manual...
I agree to that! I would like to recommend also to include the basic documentation of all components in the local doc. So you can use Ogre offline or behind a paranoid proxy of a company. The wiki can be used for collaborative work on the documentation. Then the contents must be transferred to the local documentation a few times.
User avatar
masterfalcon
OGRE Team Member
OGRE Team Member
Posts: 4270
Joined: Sun Feb 25, 2007 4:56 am
Location: Bloomington, MN
x 126
Contact:

Re: The state of Ogre's documentation

Post by masterfalcon »

I was thinking that this would be as an update to the manual so it would exist in the Docs directory of the source code as the manual does now. Just like it does now, it would be in addition to the API reference and the wiki. But unlike the wiki it would be the "official" documentation. There would very likely be crossover between them.

I'm also not opposed to changing the language in which it is written. Currently it uses Texinfo. I became partial to LaTeX in college, which is similar. Whatever we choose I think it would be beneficial to offer ways to generate the manual in various formats, html, pdf, chm, whatever.

@PhilipLB I would think that component docs, at least those in the official repo should be contained within the manual.
User avatar
only_a_ptr
Halfling
Posts: 62
Joined: Sun Apr 26, 2009 8:43 pm
x 2

Re: The state of Ogre's documentation

Post by only_a_ptr »

masterfalcon wrote:Here is my rough outline for a plan.
Good for starters, but too general IMHO.

I see 3 specific points which have to be thought over:
1 - The form. Currently, manual is in texinfo format converted to HTML. I propose to mix the manual into doxy reference, like CEGUI has: http://static.cegui.org.uk/docs/current ... rview.html
2 - The repository. I think it's a good idea to put the manual + doxy scripts in it's separate repo/branch.
3 - The responsibility. Who exactly is supposed to keep an eye on the docs? At the moment, it seems all devs are hoping for the other dev to do it. :lol:

Here's my 3-phase draft.
Phase 1: Designate a "Documentation Workforce", a team of devs responsible for the docs.
Phase 2: Create a docs-repo, upload all current docs.
Phase 3: With assistance of the community, start "patching" the docs, moving stuff from old texinfo to doxy, fixing outdated and inaccurate stuff as we go. When the docs are polished enough, just keep them up-to-date.

My 2 cents :)
Rigs of Rods is alive and kicking!
scrawl
OGRE Expert User
OGRE Expert User
Posts: 1119
Joined: Sat Jan 01, 2011 7:57 pm
x 216

Re: The state of Ogre's documentation

Post by scrawl »

1 - The form. Currently, manual is in texinfo format converted to HTML. I propose to mix the manual into doxy reference, like CEGUI has: http://static.cegui.org.uk/docs/current ... rview.html
+1 we should at least give this a try. It's cool that you can easily add links to classes / functions within the written manual.
2 - The repository. I think it's a good idea to put the manual + doxy scripts in it's separate repo/branch.
No.... please don't.
What we're seeing a lot is that people add new features or change existing ones and then just to forget updating the docs at all.
Putting them in a separate repo is going to encourage just that and the problem will get worse.
User avatar
only_a_ptr
Halfling
Posts: 62
Joined: Sun Apr 26, 2009 8:43 pm
x 2

Re: The state of Ogre's documentation

Post by only_a_ptr »

scrawl wrote:+1 we should at least give this a try.
Thanx for the positive feedback.
scrawl wrote:No.... please don't.
What we're seeing a lot is that people add new features or change existing ones and then just to forget updating the docs at all.
Putting them in a separate repo is going to encourage just that and the problem will get worse.
I see your point, but you're argumenting against yourself a bit. Currently, the docs+code are in the same repo, and, as you're saying, it has little to no positive effect on devs updating it.

But my primary concern is that the manual basically bears 2 kinds of info: 1-OGRE features, 2-info on graphics hardware and capabilities. And while the former doesn't get updated all that often IMO, the latter gets out of date fast. See this for example: http://www.ogre3d.org/docs/manual/manua ... ture-Fetch (Written 2006)

From this point of view, it would be best to have docs in a wiki, so that the more knowledgable members of the community could easily update the hardware info. But that would make it impossible to use in-doxy manual. So I'm aiming for something in between: A separate repo which mimics a wiki. This would provide a separate queue for doc-related patches, so doc-maintainers will be able to work with more comfort.
Rigs of Rods is alive and kicking!
User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
x 56
Contact:

Re: The state of Ogre's documentation

Post by Klaim »

An00biS wrote: From this point of view, it would be best to have docs in a wiki, so that the more knowledgable members of the community could easily update the hardware info. But that would make it impossible to use in-doxy manual. So I'm aiming for something in between: A separate repo which mimics a wiki. This would provide a separate queue for doc-related patches, so doc-maintainers will be able to work with more comfort.
That's also the conclusion I got to when dealing with documentation for my open source project and other projects. I think having a wiki-like repository, in particular if the repository host site provide ways to modify text online, helps a lot having one source for several documentation formats (online and offline). It's only problematic if most of your users are not technical at all (like in my open source project, most users are artist, so they often don't get github interface...) but for Ogre which is used exclusively by programmers, it should be no problem.
Post Reply