What is the purpose of your documentation?
Printed From: Codejock Forums
Category: Codejock Products
Forum Name: Toolkit Pro
Forum Description: Topics Related to Codejock Toolkit Pro
URL: http://forum.codejock.com/forum_posts.asp?TID=10492
Printed Date: 15 November 2025 at 2:05am
Software Version: Web Wiz Forums 12.04 - http://www.webwizforums.com
Topic: What is the purpose of your documentation?
Posted By: calvi
Subject: What is the purpose of your documentation?
Date Posted: 04 May 2008 at 10:30am
|
What is the purpose of your documentation? The only purpose I can discern is to pretty print the comments in the header files, which only help if you're very familiar with the classes. The only way to do that is to read the source files, which wastes a lot of time. You may have written some wonderful code, but it's no use if you don't explain what it's for, and how to use it. The documentation for the Command Bars perfectly illustrates my point. Here are some questions that should be answered on page one, but don't get answered at all: Why do I need this tool? The only information I can glean from the documentation is that it "makes it possible to design applications to the specifications desired in an application". Even worse, there's no documentation at all for MarkupPad and Resource Editor. This is simply no use in helping me decide whether they are suitable for my purposes! The documentation for the class library is equally inadequate, and now there's a competitor in the Visual C++ 2008 Feature Pack, you need strong documentation to sell the advantages of Xtreme Toolkit Pro. Please pause your headlong development and properly document what you've already done. An essential starting point is to list the purpose of each of the sample applications, and cross reference the classes they demonstrate. Expecting your customers to plough through source code is unreasonable, and unsustainable against free competition. |
Replies:
Posted By: robosport
Date Posted: 04 May 2008 at 10:20pm
|
I’m not usually a complainer but I have to whole-heartedly agree with this post. I’ve been a consistent CodeJock customer with multiple licenses for years and the lack of real documentation is the one and only thing I do not like about your solution. I’m paying for this solution to save me time, not for the privilege of studying your code examples. This is the first year I’m considering discontinuing using XTP because I simply don’t have time to dig through example projects and use trial and error to apply them to my own.
I am sure there are many great features I am not even using because I don’t know about them, until I trip over them while studying an example looking for something else, which I didn’t have time to do in the first place. Even worse I posted a question here a few weeks ago and Oleg’s answer was “You shouldn’t be using that feature, go read this example project instead.” Nowhere in the code comments did it say don’t use this public declared member function, so now I’m stuck with it for this release cycle. Real feature introductions and/or descriptions would have avoided that completely. |
Posted By: markr
Date Posted: 05 May 2008 at 10:29am
This issue has been discussed a few times over recent years (I've been a CodeJock customer for quite a while too), and it's easy to agree with what's being said here - documentation is obviously lacking. Initially, this bugged me too.  But after a while, I found that I could always find what I need through a combination of:
I would love to see CodeJock hire a full-time documentation specialist; one high-quality person doing this job full-time would help tremendously. The library implementation quality is already impossible to beat - why not improve the value proposition even further with high quality documentation? |
Posted By: ABuenger
Date Posted: 05 May 2008 at 11:42am
Once again, documentation is a waste of time! Documentation is only needed for an API like Win32 or so. ------------- Codejock support |
markr wrote:Posted By: calvi
Date Posted: 05 May 2008 at 12:47pm
Bad documentation is a waste of time. Good documentation would save the time it takes each of CodeJock's customers to learn how to use their toolkit the hard way. It would also save the time CodeJock's employees spend in this forum and in their online support, responding to questions that the documentation should answer. I call that a win-win situation!
|
Posted By: ABuenger
Date Posted: 06 May 2008 at 4:27am
|
Even the almighty Microsoft can't keep MSDN up to date. Codejock would have to invest a lot of time and money to have a top notch documentation. Time and money which is not worth the effort. Everyone but a few die-hards are happy with the samples. Samples are much better and always up to date. ------------- Codejock support |
Posted By: calvi
Date Posted: 06 May 2008 at 4:15pm
Speak for yourself. Even the samples aren't documented, so there's a big hurdle to any newcomers finding their way into XTP, and without them, it will go the way of the Stingray and Dundas MFC libraries. |
Posted By: Smucker
Date Posted: 06 May 2008 at 6:14pm
|
I like the samples for detailed information on how to interact with the libraries. Having the source code is also quite valuable, as you can step right in and figure out what it's realy doing, regardless of the (often unhelpful) names of the methods. However, especially for new users (or when wanting to use an unfamiliar feature), there is definitely a missing piece -- relatively simple descriptions of each class or control and how to get started. With this amount of overview (no, the class hierarchy does not provide that information), it would be a lot easier to get started with the toolkit or using a new aspect of it. Also, I think that someone should take all of the valuable forum information and generate a searchable knowledge base. (I would volunteer to do it on the cheap if I weren't already overwhelmed with work). This would help users by reducing the amount of time required to find an answer, and would probably help Oleg. I'm sure he gets really tired of answering the same questions over and over! |
Posted By: adrien
Date Posted: 09 May 2008 at 3:12am
|
I also find it difficult sometimes to figure out what class implements a particular visual control I want to use.
I don't know what the class is called, and there's no way to browse, so have to go through all the samples until I find an instance of it, and then try and find where it is in code.
I think documentation of every GUI element should include a screenshot of what that element looks like.
And there should be a page in the help where you can see all the elements in one place and drill through to the relevant class documentation. ------------- http://www.wingate.com - http://www.wingate.com |
Posted By: dennisV
Date Posted: 14 May 2008 at 9:49am
|
I would vote for having samples for all features of the library and then a help file that would simply point to a sample where required functionality could be found. ------------- // W7 64 Ultimate SP1 // VS 2008 // CodeJock 16.2.3 (MFC) |