The state of Ogre's documentation
-
- 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
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
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
- spacegaier
- 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
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...
Don't know what to do in your spare time? Help the Ogre wiki grow! Or squash a bug...
-
- 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
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.
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.
-
- 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
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!PhilipLB wrote:Where will the component documentation be placed? Wiki or manual?
I only tend to use the manual as a reference for the various scripts in Ogre.
- dark_sylinc
- OGRE Team Member
- Posts: 5292
- Joined: Sat Jul 21, 2007 4:55 pm
- Location: Buenos Aires, Argentina
- x 1278
- Contact:
Re: The state of Ogre's documentation
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.
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.
- 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
If you want to go this way, then don't forget also the currently very popular MarkDown (which is apparently usable by Doxigen).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.
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.
- Mikachu
- Gnoll
- Posts: 603
- Joined: Thu Jul 28, 2005 4:11 pm
- Location: Nice, France
- x 35
Re: The state of Ogre's documentation
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...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).
OgreProcedural - Procedural Geometry for Ogre3D
-
- Minaton
- Posts: 933
- Joined: Mon Mar 05, 2012 11:37 am
- Location: Germany
- x 110
Re: The state of Ogre's documentation
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.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...
- masterfalcon
- 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
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.
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.
- only_a_ptr
- Halfling
- Posts: 62
- Joined: Sun Apr 26, 2009 8:43 pm
- x 2
Re: The state of Ogre's documentation
Good for starters, but too general IMHO.masterfalcon wrote:Here is my rough outline for a plan.
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.
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!
-
- OGRE Expert User
- Posts: 1119
- Joined: Sat Jan 01, 2011 7:57 pm
- x 216
Re: The state of Ogre's documentation
+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.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
No.... please don't.2 - The repository. I think it's a good idea to put the manual + doxy scripts in it's separate repo/branch.
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.
- only_a_ptr
- Halfling
- Posts: 62
- Joined: Sun Apr 26, 2009 8:43 pm
- x 2
Re: The state of Ogre's documentation
Thanx for the positive feedback.scrawl wrote:+1 we should at least give this a try.
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.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.
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!
- 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
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.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.