U++ forum: Welcome to the forum

Re: A Few observations on U++ (lack of) documentation [message #5669 is a reply to message #5666]

Mon, 09 October 2006 08:04

arixion
Messages: 27
Registered: October 2006
Location: Southeast Asia

Promising Member

zsolt wrote on Mon, 09 October 2006 00:36

Quote:

programmers of UPP should stop programming

I can not agree with this.
It would be better to find somebody, who like writing documentation and can ask good questions from programmers of upp.
In first step, it would be a good starting point to collect and organize the lot of information in the forum.

Hmm,

forgive me if I sounded a little rude or imposing; that wasn't my intention. And I wasn't suggesting that the programmers permanently stop programming UPP; what I meant is that it is quite important that they sit down and document their sources. This is for a number of reasons:-

1. Well-documented source-code helps in the writing of tutorials, and more than that, the easy writing of newbie tutorials. Newbies can navigate around the sources more easily. Seriously, in its current state, it would be nightmarish and intimidating for a newbie to try starting to learn UPP.

2. It aids end-users who want to be involved in further developing UPP. Clearly-documented source-code means that the third-party developers can easily see what needs to be added, what needs to be amended, and what extensions can be made. That will, I hazard to guess, attract more people to the development of UPP. Besides, it makes the software look more like its professional counterparts Wx and FOX, which have extensive source documentation. Poorly-documented code means that the third-party developer needs to spend tons of time navigating through and sorting out the source-code, time which could be productively spent on development of additional controls and features to enahnce the IDE and the software. For instance, (just as an example), I'm trying to program a CodeBlocks project import function, but firstly I can't comprehend the various methods involved in XML handling or File Browsing in the IDE. The XML reference example is far from descriptive. And while Assist++ aids tremendously in code navigation, it is extreme tedium to cycle through every method and locate the appropriate file.

3. I'm not saying that development of UPP needs to terminate. Rather, perhaps a breather is needed. I think that the programmers are the best ones to document the source-code, because they should know every component's functionality completely, since they designed them. It will be much harder for third-party documenters and end-users to do this.

4. The forum information is of good quality. But as is the problem with forums (and mailing lists as well), the topics are too focused on one aspect. They are good as a quick reference point, but they are not good if a end-user or third-party developer wishes to understand the overall functionality of the various controls and library components of UPP. And fuirther more, they don't give a basic overview, which is really what new users would need. Perhaps help forums could be aided by the inclusion of sticky FAQs explaining the basic functionality of each of the classes, especially for the complex GUI components like TreeView and DocEdit/LineEdit. Then, these would not be required is source-code were documented properly.

As a brief note: I don't mind trying to write documentation - as in tutorials or man pages - for UPP, but any attempt a trying to write documentation is hindered by incomplete understanding of the source-code, which is due to lack of API documentation.

Report message to a moderator