Codejock Forums Homepage
Forum Home Forum Home > Codejock Products > Visual C++ MFC > Toolkit Pro
  New Posts New Posts RSS Feed - Documentation
  FAQ FAQ  Forum Search   Events   Register Register  Login Login

Documentation

 Post Reply Post Reply
Author
Message
calvi View Drop Down
Groupie
Groupie


Joined: 20 March 2004
Location: United Kingdom
Status: Offline
Points: 43
Post Options Post Options   Thanks (0) Thanks(0)   Quote calvi Quote  Post ReplyReply Direct Link To This Post Topic: Documentation
    Posted: 20 March 2004 at 3:24am

I'd just like to say how disappointed I am with the documentation for Xtreme Toolkit Pro.  If you are going to rely on generating it from header files, you really must check that what's generated is actually helpful.  For example, select this entry in the online help:

  Xtreme Toolkit Pro v 8.61/Classes/CXTResize

Scroll down to the table of methods and look at  the entries for SetResize.  There are 7 of them, 6 of which have almost the same description.  The corresponding description is displayed if you click on any of the entries.  None of the descriptions explain how to use the parameters.  If you select the 6th variant, then follow through by clicking on XT_SIZING, you get the recursive description that "The XT_SIZING structure is a stand alone helper structure class. It is used by the CXTResize class to maintain size and ID for a particular window being sized.".  It would be far better to say "we couldn't be bothered to document this stuff, so look at FlatComboDlg.cpp for clues, and step through with a debugger, if it still doesn't make sense".  At least that would save your customers from wasting their time trying to glean something useful from the documentation!

Other criticisms:

1. There is no list of sample code, stating what features each sample demonstrates.
2. There are very few tutorials: use of resizable dialog boxes is clearly missing.
3. Classes are not categorized by function.
4. There is no introductory material summarizing all the capabilities of the library, with links to the detailed documentation.

I could go on, but I haven't the time.  If you are open to suggestions, sit beside an experienced MFC programmer, who's just starting to use your library, and silently watch them struggle.  Then write the missing documentation.



Edited by calvi
Back to Top
calvi View Drop Down
Groupie
Groupie


Joined: 20 March 2004
Location: United Kingdom
Status: Offline
Points: 43
Post Options Post Options   Thanks (0) Thanks(0)   Quote calvi Quote  Post ReplyReply Direct Link To This Post Posted: 21 March 2004 at 6:48am

I've just come across another gem, which I'll share with you:

CXTTabCtrlBaseEx

CXTTabCtrlBaseEx is a CXTTabCtrlBase derived class. It is used to create a CXTTabCtrlBaseEx class object.

It's certainly a concise statement, but not a single word adds any understanding to the purpose of this class, how to use it, nor its advantages over CXTTabCtrlBase (the documentation of which is no better)!

This sort of thing would be acceptable for free software, but when there's a price tag, you expect better.  I've seen much better documentation for free software from CodeProject.  In fact, I was only able to understand how to use CXTResizeDialog after reading this article:

http://www.codeguru.com/Cpp/W-D/dislog/resizabledialogs/arti cle.php/c1925/

 

Back to Top
msamocha View Drop Down
Newbie
Newbie
Avatar

Joined: 07 March 2004
Location: Israel
Status: Offline
Points: 30
Post Options Post Options   Thanks (0) Thanks(0)   Quote msamocha Quote  Post ReplyReply Direct Link To This Post Posted: 21 March 2004 at 9:12am

I Agree. The XTP Documentaion needs a lot of work.

The Tutorials are good but insufficient. You have to struggle with the sample projects to figure out how to program what you want, and the documentation in the help is far from sufficient. There is no general information for the purpose and the way to use the XTP classes/functions in the docs.

Back to Top
vladsch View Drop Down
Newbie
Newbie


Joined: 04 February 2004
Location: Canada
Status: Offline
Points: 30
Post Options Post Options   Thanks (0) Thanks(0)   Quote vladsch Quote  Post ReplyReply Direct Link To This Post Posted: 26 March 2004 at 12:23pm

I was initially very frustrated with the documentation. To the point that I sent tons of e-mails and suggestions to the support team. This was in the first week of trying to learn how to apply it to my application.

I also made the same suggestion that samples should be indexed based on features that they use to make finding relevant code easier.

In my app menus and toolbars are completely dynamic and defined via configuration scripts. So none of the standard functions of loading them from existing resources applied. Also, the initialization of these could not be done during window creation as in all the samples because the script engines including VBA are not initialized until some time after the creation of the window. None of the documentation was relevant even at hinting where I should start looking much less provide the relevant information.

However, after the initial frustration and reluctance to dive into the XTP source (headers and source files) I finally did dive into these. What I discovered is that if you are willing and able to work with the source, frustration will diminish enourmously.

The toolkit is well architected and easy reading (as easy as heavily modal, event driven application can be). The added advantage is to be able to single step and break point live code to get a better understanding of how it works.

I also discovered that the functionality I needed to use is way out of the beaten path and was either missing altogher or had some "omissions" or bugs which were easy to fix once I got familiar with the layout of the source files. My version now has some tweaks that allow completly dynamic menus and toolbars which can also be customized. The added functions were quickly built from existing functions as a starting point with a little experimentation.

I no longer refer to the documentation except for very rare circumstances such as finding an Enum that I know is listed there, but not much more. I go directly to the header files and source files to get my answers.

In the end I was able to get all the functionality working in my non-standard app. The re-use of CXTPControl and CXTPControls for all control functions in menus, command bars, popups makes creation and manipulation of these much cleaner that the previous code that dealt directly with Windows versions of the same.

It is unfortunate that the documentation proves such a turn off initially that some user can drop the toolkit altogether before discovering its power and beauty. It is well written and easy to find your way around once its "undocumented" architectural concepts are understood.

However, from my communication with XTP they are very aware of the problem and are actively addressing it. Also in their defense I must also add that as I understood the toolkit breadth and depth better I also saw that documenting the complexity of the toolkit will not be an easy task and will take a lot of iterative effort.

Back to Top
calvi View Drop Down
Groupie
Groupie


Joined: 20 March 2004
Location: United Kingdom
Status: Offline
Points: 43
Post Options Post Options   Thanks (0) Thanks(0)   Quote calvi Quote  Post ReplyReply Direct Link To This Post Posted: 27 March 2004 at 2:55pm

I can't agree with you about the benefits of reading the headers, rather than the documentation, because the latter is created from the former.

As another example of how useless the documentation is, I wanted a menubar with command bitmaps that match the equivalent toolbar commands.  I missed the relevant entry in the contents, because there was nothing obvious starting with CXTMenu, but subsequently discovered a whole bunch of classes starting with CXTP (the reason for which is not documented), including CXTPMenuBar.  Does it do what I want?  Who can tell, from a description like this: "CXTPMenuBar is a CXTPToolBar derived class".  What is the point of that?

It's really not that difficult to write useful documentation.  You just have to ask yourself what the reader needs to know, and write the answers.  In this case, the obvious requirements are:

1. What will this class do for me?
2. How do I implement it in my application?

The nitty gritty may be obtained from the header files, but I'm only inclined to read them if I'm already confident that the class has the capabilities I need!

Back to Top
ddyer View Drop Down
Groupie
Groupie
Avatar

Joined: 01 December 2003
Location: United States
Status: Offline
Points: 40
Post Options Post Options   Thanks (0) Thanks(0)   Quote ddyer Quote  Post ReplyReply Direct Link To This Post Posted: 31 March 2004 at 8:00am

Calvi,

Everyone agrees with you, he is just trying to help you out.  This has been discussed at length before.  Be thankful you started with the version you did :)

They are making progress bit by bit.

 

edit: idiots like me need a lot more hand-holding than average, so Im sure I backed up plenty of their mail folders in the past :)



Edited by ddyer
Back to Top
Parker View Drop Down
Newbie
Newbie
Avatar

Joined: 15 September 2003
Status: Offline
Points: 4
Post Options Post Options   Thanks (0) Thanks(0)   Quote Parker Quote  Post ReplyReply Direct Link To This Post Posted: 02 April 2004 at 12:35am
The documention is useless
Best Regards,


-Parker      

___________________
Parker McCauley
Staff Engineer, R&D
Advanced Control Systems
Email : pmac@acsnorth.net
Back to Top
Andrei View Drop Down
Newbie
Newbie
Avatar

Joined: 01 May 2004
Status: Offline
Points: 7
Post Options Post Options   Thanks (0) Thanks(0)   Quote Andrei Quote  Post ReplyReply Direct Link To This Post Posted: 01 May 2004 at 1:39am

Blah-blah-blah.



Edited by Andrei
Back to Top
Ark42 View Drop Down
Senior Member
Senior Member
Avatar

Joined: 20 October 2003
Status: Offline
Points: 291
Post Options Post Options   Thanks (0) Thanks(0)   Quote Ark42 Quote  Post ReplyReply Direct Link To This Post Posted: 02 May 2004 at 12:36pm

Well poor documentation might be acceptable if so many posts and emails for support weren't simply ignored so often as well.
Back to Top
Parker View Drop Down
Newbie
Newbie
Avatar

Joined: 15 September 2003
Status: Offline
Points: 4
Post Options Post Options   Thanks (0) Thanks(0)   Quote Parker Quote  Post ReplyReply Direct Link To This Post Posted: 02 May 2004 at 6:23pm
Originally posted by Andrei Andrei wrote:

I am a little surprized at the amount of whining out there.I thought programming was about overcoming difficulties, wasn't it ?



You must not have paid for yours. Most of us have stuggled through the shortcomings of Microsoft documentation over the years and have paid good money for this library. It is intended to speed development. Having to reverse engineer the code to figure out what it does severly detracts from this goal. I am happy with the product, but very happy with the documentation.

Edited by Parker
Best Regards,


-Parker      

___________________
Parker McCauley
Staff Engineer, R&D
Advanced Control Systems
Email : pmac@acsnorth.net
Back to Top
Ark42 View Drop Down
Senior Member
Senior Member
Avatar

Joined: 20 October 2003
Status: Offline
Points: 291
Post Options Post Options   Thanks (0) Thanks(0)   Quote Ark42 Quote  Post ReplyReply Direct Link To This Post Posted: 02 May 2004 at 6:33pm

And not only do we pay for the library up front, but I personally also paid for the year of SUPPORT and upgrades.  The upgrades are fairly easy, since their order system lets us download new versions fairly automatically, but the support part, which I am paying for, really can be lacking at times.  The documentation is poor, so I post on the forums.  My hope by posting on the forums is that my question and their answers will help other users and cut down on the number of duplicate repies codejock staff has to make if many people were to ask the same question by email.  Unfortunately a lot of forum posts go unanswered, so I have to send them emails, but even then, sometimes I get a response within a day by email, sometimes my emails are just completely ignored like the forum post. 
While the product seems good, the staff really is not making me want to pay another $245.00 when it comes time to renew my subscription.  What benefit would I get from paying more money if nobody is going to help answer my questions? Its not like $245.00 is too expensive for a single programmer, not even close. It would be worth me paying more then $245 quite easily, if I was guarenteed support and timely fixes to bugs, but I doubt its going to happen.

That what some of us are paying for, or want to be paying for: support. Not just the library itself.




Edited by Ark42
Back to Top
Andrei View Drop Down
Newbie
Newbie
Avatar

Joined: 01 May 2004
Status: Offline
Points: 7
Post Options Post Options   Thanks (0) Thanks(0)   Quote Andrei Quote  Post ReplyReply Direct Link To This Post Posted: 05 May 2004 at 12:09pm

Blah-blah-blah.



Edited by Andrei
Back to Top
Ark42 View Drop Down
Senior Member
Senior Member
Avatar

Joined: 20 October 2003
Status: Offline
Points: 291
Post Options Post Options   Thanks (0) Thanks(0)   Quote Ark42 Quote  Post ReplyReply Direct Link To This Post Posted: 05 May 2004 at 1:49pm
You must be joking Andrei, or else you must be a codejock employee under an alias.

As Calvi said above, the documentation in the source code comments is about as good as:

CXTTabCtrlBaseEx

CXTTabCtrlBaseEx is a CXTTabCtrlBase derived class. It is used to create a CXTTabCtrlBaseEx class object.

Incredibly true but all together useless information that you can tell without needing a comment.

Besides, the entire point of paying a yearly fee for support is to get support.  Telling customers to just read through the source code is a complete joke. That is NOT support. Support is answering all the customer's questions in a timely manner.  Even if answering questions involves saying things like "No, the library does not do that, but it may in the future" or "No, the library can not do that, and probably never will".  Even if answering the customers questions involves repeating information found elsewhere, or pointing them to a specific example/section of the tutorial, etc.  Ignoring emails and forums posts is really going to hurt codejock in the long run.

What is so hard about answering the questions posted here in the forums?  I see lots of posts go unanswered every day.  Are the employees overwhelmed? Do they need to hire more?  Are too many non-paying people asking for support? Does there need to then be a form in the customer login to submit the support request along with your username to proove you are a paying customer automatically? What about a read-only group of forums that you can only get post-access to if you buy the product, and your access is taken away after your support period expires?  Obviously something can be done about the problem, there are lots of options here.

Back to Top
Andrei View Drop Down
Newbie
Newbie
Avatar

Joined: 01 May 2004
Status: Offline
Points: 7
Post Options Post Options   Thanks (0) Thanks(0)   Quote Andrei Quote  Post ReplyReply Direct Link To This Post Posted: 08 May 2004 at 4:28am

Blah-blah-blah.



Edited by Andrei
Back to Top
Ark42 View Drop Down
Senior Member
Senior Member
Avatar

Joined: 20 October 2003
Status: Offline
Points: 291
Post Options Post Options   Thanks (0) Thanks(0)   Quote Ark42 Quote  Post ReplyReply Direct Link To This Post Posted: 08 May 2004 at 12:01pm

I think you are completely missing the point here.  Lets pretend for a minute that the source code was easy to dig through, that right clicking and picking "Go To Definition Of ..." actually lead to a piece of code with a useful comment next to it, and that the entire documentation was very well done and that there were 100s of tutorials as well.

Alright, now myself, and many others, have paid for a year of free upgrades and support.  That support includes phone support, email support, and forums support.  Paying this yearly fee should entitle us to priority responses to our questions so that we may better understand a very complex library and more quickly use it.  The point is, the people buying the library aren't nearly familiar with it as the people who are writing it, and we are paying money to have those people help us understand it.  There is no need to start bashing people here. There are no stupid questions.  If multiple people ask the same seemingly easy questions, that does not mean those people are all being lazy or can't dig though the code.  It means people unfamiliar with the code have a hard time understanding the purpose of parts of it.

Quite honestly, adding lots of new features to the library is not in most of our best interests.  Fixing bugs does not count as new features of course.  I would be perfectly happy staying with the original v8.60 feature set, provided that I could get bugs fixed and understood how to use all the features.

I don't really believe that a few questions that may be seemingly stupid and trivial to the codejock developers is going to slow them down from adding features or fixing bugs.  As an example, the installer software I use Inno Setup, which is a completely free program, has a great help file that explains all of its complicated features very well.  On top of that, the single author of the program provides free support via a newsgroup, that gets over 50 new posts every day, yet he still manages to answer them all, many times within a couple hours, all while constantly fixing bugs and adding new features.  Now many of the questions received on the forum are in fact answered in that great help file, but people post answers pointing people to the appropriate help file section, and when a question is completely offtopic and not something an installer would even do, there is at least an answer to the post letting the person know that somebody at least read their question and they will have to look elsewhere for help.

With codejock, the documenation file is very useless.  It seems entirely generated from comments in the source code, which are 95% true statements that have no actual meaning to them.  Occasionally I see the words "used internally" and thus try to ignore that class and find another, but otherwise I don't use the documentation at all.  There is a smaller tutorial file, that is actually very well done, and covers some of the basic topics.  Beyond the tutorial, I resort to looking at the samples, and I don't see a particular feature in any of the samples, sometimes I wonder if its something that the library can do, but was just not included in the sample, or if its simply not a feature yet.

Now, despite all of the posts, and me reaching "Groupie" status already, I'm not angry with codejock.  The product works very well and looks very nice, and I am able to continue developing my application despite a couple minor bugs here and there.  I do wish codejock would do something to differentiate between people who continue to pay the yearly support fee and people who are asking questions while not paying.  I also wish they would at the very least post replies to questions sooner saying "we will look into this" or "this is not something we can help you with".  Overall the product is very good and the support does happen, sometimes just a little later on.

Back to Top
Sven View Drop Down
Senior Member
Senior Member


Joined: 21 August 2003
Location: Germany
Status: Offline
Points: 127
Post Options Post Options   Thanks (0) Thanks(0)   Quote Sven Quote  Post ReplyReply Direct Link To This Post Posted: 08 May 2004 at 2:01pm

I have to agree with Andrei, the source code is the best documentation you can get. I didn't use the help file in any way, the source code and the class layout are well designed. I spent some time with the debugger and tried to understand the working model of the Toolkit.

At the beginning (I used another library before) I had some questions how I can achieve some things with the Toolkit and all my support calls (via eMail) are answered.

Back to Top
Andrei View Drop Down
Newbie
Newbie
Avatar

Joined: 01 May 2004
Status: Offline
Points: 7
Post Options Post Options   Thanks (0) Thanks(0)   Quote Andrei Quote  Post ReplyReply Direct Link To This Post Posted: 08 May 2004 at 11:51pm

Blah-blah-blah.



Edited by Andrei
Back to Top
Ark42 View Drop Down
Senior Member
Senior Member
Avatar

Joined: 20 October 2003
Status: Offline
Points: 291
Post Options Post Options   Thanks (0) Thanks(0)   Quote Ark42 Quote  Post ReplyReply Direct Link To This Post Posted: 08 May 2004 at 11:57pm

I don't see how this is even a right/wrong issue.  It seems purely a matter of opinion. My opinion is that paying for the year of support entitles me to support.  If that is not true, I don't see any reason I should renew this support contract, and so, I probably won't.

Back to Top
Parker View Drop Down
Newbie
Newbie
Avatar

Joined: 15 September 2003
Status: Offline
Points: 4
Post Options Post Options   Thanks (0) Thanks(0)   Quote Parker Quote  Post ReplyReply Direct Link To This Post Posted: 09 May 2004 at 8:09am
Ark42.... Well said

perhaps if Andrei didn't have to spend so much time reading the comments in the code he would have more free time - lol

Edited by Parker
Back to Top
Ark42 View Drop Down
Senior Member
Senior Member
Avatar

Joined: 20 October 2003
Status: Offline
Points: 291
Post Options Post Options   Thanks (0) Thanks(0)   Quote Ark42 Quote  Post ReplyReply Direct Link To This Post Posted: 09 May 2004 at 9:05am

Man, like anybody should really believe this immaturity. Check out this private message I just got:

arc42,

You're the most stupid asshole I've ever met. If only I could get at you I'd beat all sh*t outa you, son of a bitch.

Andrei
Back to Top
Ark42 View Drop Down
Senior Member
Senior Member
Avatar

Joined: 20 October 2003
Status: Offline
Points: 291
Post Options Post Options   Thanks (0) Thanks(0)   Quote Ark42 Quote  Post ReplyReply Direct Link To This Post Posted: 09 May 2004 at 9:53am

I hope this Andrei guy is not a US citizen, because I'm quite sure that is grounds for a subpoena, but if he is a codejock employee (and why else would he get so violently agry at me for these comments?) I'm sure it wouldn't matter to obtain any logs of his IP address anyway.

In all fairness, I do think the documentation is improving, but it must be a daunting task given the sheer volume of code that exists in the library.  The docking pane classes seem difficult to understand and the comments offer no additional help, which was what I was working with recently, but I just looked at CXTButton and CXTThemeManager and the comments there are somewhat helpful, as they should be.  I'm sure, given enough time, the rest of the comments across the code will be changed to have more use.

Back to Top
Andrei View Drop Down
Newbie
Newbie
Avatar

Joined: 01 May 2004
Status: Offline
Points: 7
Post Options Post Options   Thanks (0) Thanks(0)   Quote Andrei Quote  Post ReplyReply Direct Link To This Post Posted: 09 May 2004 at 11:10am
Blah-blah-blah.
Back to Top
aaxemen View Drop Down
Newbie
Newbie


Joined: 29 September 2004
Status: Offline
Points: 12
Post Options Post Options   Thanks (0) Thanks(0)   Quote aaxemen Quote  Post ReplyReply Direct Link To This Post Posted: 20 October 2004 at 1:35pm
I think Andrei is actually my twelve year old...
Back to Top
 Post Reply Post Reply
  Share Topic   

Forum Jump Forum Permissions View Drop Down

Forum Software by Web Wiz Forums® version 12.04
Copyright ©2001-2021 Web Wiz Ltd.

This page was generated in 0.219 seconds.