|
What is the purpose of your documentation? |
Post Reply 
|
| Author | |
calvi 
Groupie 
Joined: 20 March 2004 Location: United Kingdom Status: Offline Points: 43 |
 Post Options
 Thanks(0)
 Quote Reply
 Topic: What is the purpose of your documentation?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. |
|
 |
|
|
robosport
Groupie
Joined: 20 June 2005 Location: United States Status: Offline Points: 62 |
Post Options
Thanks(0)
Quote Reply
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. |
|
|
|
|
markr
Senior Member 
Joined: 01 August 2004 Status: Offline Points: 442 |
Post Options
Thanks(0)
Quote Reply
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? |
|
|
|
|
ABuenger
Newbie 
Joined: 02 February 2006 Status: Offline Points: 1075 |
Post Options
Thanks(0)
Quote Reply
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
|
|
|
|
|
calvi
Groupie
Joined: 20 March 2004 Location: United Kingdom Status: Offline Points: 43 |
Post Options
Thanks(0)
Quote Reply
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!
|
|
|
|
|
ABuenger
Newbie
Joined: 02 February 2006 Status: Offline Points: 1075 |
Post Options
Thanks(0)
Quote Reply
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
|
|
|
|
|
calvi
Groupie
Joined: 20 March 2004 Location: United Kingdom Status: Offline Points: 43 |
Post Options
Thanks(0)
Quote Reply
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. |
|
|
|
|
Smucker
Senior Member
Joined: 02 February 2008 Status: Offline Points: 156 |
Post Options
Thanks(0)
Quote Reply
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! |
|
|
|
|
adrien
Senior Member
Joined: 30 April 2007 Location: New Zealand Status: Offline Points: 449 |
Post Options
Thanks(0)
Quote Reply
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.
|
|
|
|
|
dennisV
Senior Member
Joined: 07 October 2004 Location: Australia Status: Offline Points: 242 |
Post Options
Thanks(0)
Quote Reply
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) |
|
|
|
|
Post Reply
|
|
Tweet
|
| Forum Jump | Forum Permissions You cannot post new topics in this forum You cannot reply to topics in this forum You cannot delete your posts in this forum You cannot edit your posts in this forum You cannot create polls in this forum You cannot vote in polls in this forum |
Topic Options
markr wrote: