Lack of Documentation, Samples and Demo's

[Van]

I think CEGUI could be a fine library. My biggest complaint about CEGUI is the lack of documentation and samples. DoxyGen is NOT documentation. It makes for a nice REFERENCE but that is all. I really wish someone who really knows this library would spend some time creating some documentation with some samples.

I am tired of spending hours of going through the CEGUI code to figure out what and how to do something. My previous post about Drag and Drop not supported in the list boxes is a fine example of how CEGUI wasted my time. I know it wasn't claimed that it was support, but no where did it say it WASN'T supported either and I would think that most people would assume it was support.

Now I am trying to figure the damn PopupMenu. I understand the concept, but I can't get it working.. Ah, I will look at the documentation to see how its done - nope, nothing there - what a surprise. OK, I will look at the Demo's. Crap, nothing there either. I'll check the Wiki - WIKI WORTHLESS.

Someone needs to break down and spend some time doing documentation and samples. They don't have to be working samples, but something like this in the wiki would be nice:

Code: Select all

Steps to creating a PopupMenu:

1. blah
2. blah blah
3. blah and blah but can't do blah

Here is example code:
 myfunction()
 {
    some code
 }


I know I am being critical but there is insufficient amount of knowledgable CEGUI people in the community and it puts an undo burden on the only TWO people that do know the library. This isn't like the Ogre or Newton communities where there are alot of people and plenty of documentation and examples.

And before someone comes up with the smartass remark of Why don't you do the documentation and contribute - think about: Would I be making this post if I knew CEGUI? I do contribute, I have contributed to ALL the libraries I use and I will do the same with CEGUI. But I have to get a point where I am confindent with the product.

So, will the developers of CEGUI PLEASE get some documentation and samples into the wiki?

[Exsortis]

Documentation is my least favorite thing to do.

That being said, it takes time to write, as do samples and demos. And just to pour a little lemon juice into your paper cut, significant changes are on the horizon.... Why document (extensively) what you know will change?

The docs and demos and samples are all important and will get done. Just please be patient. Right now, the best way to learn is to look at what is already there, and look at the code. Sorry if that doesn't suit you right now, but that's the state of things.

-E

[Van]

Exsortis wrote:
Documentation is my least favorite thing to do.

Yea, documentation is the least of every programmers thing to do and that goes for me too - but I still have to do it and so does every developer here at some point. It's a catch 22 situation. If you don't create documentation, then it's difficult to grow a base of experienced users and that leaves the developer to provide the support. If you create some documentation it will accellerate the learning curve and the community with grow and create more experienced users which could help contribute to the project in one fashion or another - like provide support. It's difficult to be a developer and a support person at the same time. You either a) can't get anything done or b) one side suffers (dev or support). In this case, support is suffering. CEGUI may be the greatest library ever written, but if there is no documentation or support then it's worthless.

Exsortis wrote:
That being said, it takes time to write, as do samples and demos. And just to pour a little lemon juice into your paper cut, significant changes are on the horizon.... Why document (extensively) what you know will change?

That's nothing but a lame excuse that demonstrates lazyness and a lack of professionalism on your part. Their are always significant changes on the horizon for any development project. You have to get started somewhere and sometime and it might as well be now. Once the base documentation is in place then people can morph and change it to adapt to changes made in the library. This is the beauty of the Wiki.

I am not asking for extensive, detailed professional documentation. Usually that kind of documentation is bloated to the point that no one can find what they are looking for which makes the documentation equally worthless. Just some quick and dirty how-to's in the wiki would be nice.

Exsortis wrote:
The docs and demos and samples are all important and will get done. Just please be patient. Right now, the best way to learn is to look at what is already there, and look at the code. Sorry if that doesn't suit you right now, but that's the state of things.

I guess it's not important enough as you are sluffing it off with the typical developer rhetoric. Look at what is already there? Obviously you didn't read my post closely - The DEMO's only have the basics library functions and NONE of the new features. There are NO examples of how to implement new features. And, I have been trapsing through the code to figure it out - its a waste of my time and I can see how it does nothing but frustrate other CEGUI users.


Here is my suggestion:

The developers should create a HOW-TO section in the wiki. Then, once per day or week, each developer should pick a topic and create a basic How-To on it. My suggested topics are (not in any order):

o Create a Window
o Create a Listbox and Add Items
o Create a MultiColumnList box and add items
o Create PopupMenu
o Drag and Drop
o Capturing Mouse Events: Which button was pressed?
o Capturing key stroke events
o The CEGUI Event system
o The difference between a SHEET and a WINDOW

IMHO, I think the items in the above list that should done first should be items where there are no examples or documentation, like: PopupMenu and MultiColumnList and Drag and Drop. I assure you, once you guys get this ball rolling it will take off on its own and people (like me) will begin to contribute once the knowledge and expeirence base grows.

[Van]

And just to show that I'm not full of smack....

Wiki->CodeSnippets->MultiColumnList

URL: http://www.cegui.org.uk/wiki/index.php/MultiColumnList

That took me about an hour to write. It's not perfect but at least it something that people can review, commment, edit, change, etc. I don't know about other people but this is the type of documentation I like see..

So, I would expect to see others follow my example and contribute: both the user base and the developers.

[martignasse]

Someone needs to break down and spend some time doing documentation and samples. They don't have to be working samples, but something like this in the wiki would be nice:.

You know what, i was thinking exactly the same when i was responding to you'r drag and drop question
and that's what i tried to help.

That took me about an hour to write. It's not perfect but at least it something that people can review, commment, edit, change, etc. I don't know about other people but this is the type of documentation I like see...

and i tried to do the same with drag and drop on ListBoxItem. but it's not finished...
(juste begenning with CEGUI and only coding 6~h/week)

I'll put it on the wiki when done, maybe after your's if you succed on it ?

I am tired of spending hours of going through the CEGUI code to figure out what and how to do something. My previous post about Drag and Drop not supported in the list boxes is a fine example of how CEGUI wasted my time. I know it wasn't claimed that it was support, but no where did it say it WASN'T supported either and I would think that most people would assume it was support.

I'm not completely agee with you.

even if i spend hours too,
i considere it's more cause lake of OO, DP, C++ knowledge to rapidly learning the CEGUI API.

I believe without this in scope, it's easy to lost myself in tons of sources...

That said, i second you in the wiki "How to" part.

...and always curiouse about your drag and drop story issue

[martignasse]

Van,

I made a HOW-TO section on the wiki "CodeSnippets" page with your topics suggest.

but i let you moving your MultiColumnList in it cause i don't know how to do it.

now, i go back to finish DragAndBoxList...

[jacmoe]

Van wrote:
I would expect to see others follow my example and contribute: both the user base and the developers.

I think the developers should concentrate on what they do best: writing code with good comments in it.

[Van]

jacmoe wrote:

Van wrote:
I would expect to see others follow my example and contribute: both the user base and the developers.

I think the developers should concentrate on what they do best: writing code with good comments in it.

Yea, I see what you mean. So, I suppose the people at Linux, Microsoft, MySQL, PHP, and all those other APIs should follow your suggestion as well..

[jacmoe]

The devs at Microsoft: There's a whole lot of people employed there who does nothing but write docs all day long.

For OS projects, do you really want the devs to spend time on writing newbie guides, and stuff like that?
I bet you are getting impatient when the release rate goes way down - they simply don't have the time to do both things.
Without pay.

Amazingly, CE tries to do both sometimes.
Just take a look at the Falagard guide.