Hello,

I have been testing the disko framework for some days now, I am very happy with it. It is definitely a great library.

Nevertheless, I believe that the learning curve is a bit slow due to the lack of documentation. The tutorials are great but they are not complete.

Therefore, my suggestion is to create some sort centralised of online reference doc.

I know this is a time consuming task. But it would certainly contribute to the proliferation of the framework.

Regards,
André

Hello André,

thank you for your notes.

We are currently working on a new website structure and we plan to revise the documentation section. We intend to release the new website at the end of january. Do you have some more informations about the weaknesses of our documentation or do you have some topics we should explain more detailed?

Thank you in advance ...

Happy new year!

Guido

Hello Guido,

It is good to know that your are updating your website.

I can highlight some of the topics that I think deserve some better explanation:

• My first suggestion is to have a centralised online reference doc. Anyone trying to get used to disko will find the information a bit spread around the morphinetv and the disko websites.


• The xml elements used in dialog and theme files should also be somehow integrated into the main reference doc. I actually found a description at http://wiki.morphine.tv/tiki-index.php_page=elements. But not only I believe it needs to be updated, but I also think it should be on the main disko website documentation section.


• For a developer using disko, it is important to deeply understand it's architecture. Again, I found the page http://wiki.morphine.tv/tiki-index.php_page=Introduction, but I believe the subject deserves a deeper description.


• Regarding the API reference page, it lacks comments. It would be extremely useful to attached a short description to each class and member functions. Moreover I believe that the API reference page should mention only the "external" interface of the framework, and not the classes and functions used internally by disko.


• Another interesting feature you might consider including within the reference doc, is the inclusion of user comments. A great example is the Postgres documentation page.


• Exception handling within the disko framework also needs more explanation. For example, I just found out that I can catch an MMSError* which contains error information details. I have not found any reference to this so far on the available documentation.


• InputManager also lacks some usage documentation. For example, I still was not able to figure out how to associate tasks/functions with specific user input inputs.


• I have not found any detailed explanation of the options within the diskorc.xml. It is crutial to know exacly how to configure runtime options using that file.


• Finally, I would really like to know which actions must be done just before program termination. I found the function mmsRelease() but the examples don't use it. Does it release all the dynamic allocated memory (like Qt does)?

These are the main topics where I have found the current documentation incomplete. I truly hope this information is somehow useful to you guys.

Nevertheless, I would like to emphasise once again that so far I found disko to be great library, despite the fact is not very well documented.

Best regards & happy new year!

André