Codejock Developer Community : What is the purpose of your documentation? http://forum.codejock.com/ Copyright (c) 2006-2013 Web Wiz Forums - All Rights Reserved. Sat, 04 Apr 2026 13:38:39 +0000 Wed, 14 May 2008 09:49:16 +0000 http://blogs.law.harvard.edu/tech/rss Web Wiz Forums 12.04 360 forum.codejock.com/RSS_post_feed.asp?TID=10492 <![CDATA[Codejock Developer Community]]> http://forum.codejock.com/forum_images/codejock-logo.gif http://forum.codejock.com/ <![CDATA[What is the purpose of your documentation? : I would vote for having samples...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=35193&title=what-is-the-purpose-of-your-documentation#35193 Author: dennisV
Subject: 10492
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.
]]> Wed, 14 May 2008 09:49:16 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=35193&title=what-is-the-purpose-of-your-documentation#35193 <![CDATA[What is the purpose of your documentation? : I also find it difficult sometimes...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=35000&title=what-is-the-purpose-of-your-documentation#35000 Author: adrien
Subject: 10492
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.
]]> Fri, 09 May 2008 03:12:55 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=35000&title=what-is-the-purpose-of-your-documentation#35000 <![CDATA[What is the purpose of your documentation? : I like the samples for detailed...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34821&title=what-is-the-purpose-of-your-documentation#34821 Author: Smucker
Subject: 10492
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!

]]> Tue, 06 May 2008 18:14:06 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34821&title=what-is-the-purpose-of-your-documentation#34821 <![CDATA[What is the purpose of your documentation? : ABuenger wrote:Everyone but...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34818&title=what-is-the-purpose-of-your-documentation#34818 Author: calvi
Subject: 10492
Posted: 06 May 2008 at 4:15pm

Originally posted by ABuenger ABuenger wrote:

Everyone but a few die-hards are happy with the samples. Samples are much better and always up to date.

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.
]]> Tue, 06 May 2008 16:15:33 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34818&title=what-is-the-purpose-of-your-documentation#34818 <![CDATA[What is the purpose of your documentation? : Even the almighty Microsoft can&#039;t...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34768&title=what-is-the-purpose-of-your-documentation#34768 Author: ABuenger
Subject: 10492
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.

]]> Tue, 06 May 2008 04:27:23 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34768&title=what-is-the-purpose-of-your-documentation#34768 <![CDATA[What is the purpose of your documentation? : ABuenger wrote:Once again,...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34724&title=what-is-the-purpose-of-your-documentation#34724 Author: calvi
Subject: 10492
Posted: 05 May 2008 at 12:47pm

Originally posted by ABuenger ABuenger wrote:

Once again, documentation is a waste of time! Documentation is only needed for an API like Win32 or so.

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!
]]> Mon, 05 May 2008 12:47:45 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34724&title=what-is-the-purpose-of-your-documentation#34724 <![CDATA[What is the purpose of your documentation? : markr wrote:Reviewing samplesReviewing...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34720&title=what-is-the-purpose-of-your-documentation#34720 Author: ABuenger
Subject: 10492
Posted: 05 May 2008 at 11:42am

Originally posted by markr markr wrote:


  • Reviewing samples
  • Reviewing library source code
  • Searching these forums
  • Posting on the forums (e.g. asking for help)


Once again, documentation is a waste of time! Documentation is only needed for an API like Win32 or so.

]]> Mon, 05 May 2008 11:42:33 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34720&title=what-is-the-purpose-of-your-documentation#34720 <![CDATA[What is the purpose of your documentation? : This issue has been discussed...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34713&title=what-is-the-purpose-of-your-documentation#34713 Author: markr
Subject: 10492
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:
  • Reviewing samples
  • Reviewing library source code
  • Searching these forums
  • Posting on the forums (e.g. asking for help)
Is this process a bit more time consuming than referencing a well-written tutorial or "how to" article? Yes, of course. However, that time spent is trivial compared to developing UI components of this quality on your own (or buying a competing product that's a fraction of the quality).

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?
]]> Mon, 05 May 2008 10:29:13 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34713&title=what-is-the-purpose-of-your-documentation#34713 <![CDATA[What is the purpose of your documentation? : I’m not usually a complainer but...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34664&title=what-is-the-purpose-of-your-documentation#34664 Author: robosport
Subject: 10492
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.
 
]]> Sun, 04 May 2008 22:20:44 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34664&title=what-is-the-purpose-of-your-documentation#34664 <![CDATA[What is the purpose of your documentation? : What is the purpose of your...]]> http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34648&title=what-is-the-purpose-of-your-documentation#34648 Author: calvi
Subject: 10492
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?
What are its limitations? (eg. is it suitable for use with MDI?)
How does it fit in with Visual Studio's UI designer?
What's its output and how does my application load it?
How do I link event handlers to the controls it creates?

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.

]]> Sun, 04 May 2008 10:30:54 +0000 http://forum.codejock.com/forum_posts.asp?TID=10492&PID=34648&title=what-is-the-purpose-of-your-documentation#34648