[ka-Map-users] Documentation? Wiki? New versions?

[Paul Spencer]

I will probably use jsdoc (http://jsdoc.sourceforge.net) for the  
inline documentation.  This will be of some help to the hard core  
developers, but I have found that it is normally more useful to have  
higher level documentation that describes how to use the API (as  
opposed to documenting what it is) ...

Paul

On 17-Dec-05, at 1:40 PM, Stephen Woodbridge wrote:

> Hi Paul,
>
> One of our Where2GetIt engineers, Matt, has been looking at ka-map  
> and was grumbling about documentation also. He suggested using  
> javadoc because that would allow the comments to be embedded in the  
> code where they are more likely to get updated as the code changes.  
> Also this is what some other javascript libraries are using. It has  
> the benefit of the the fact there are some standard tools for  
> extracting and formating the javadoc.
>
> I think agreeing on a standard, what ever it may be, for how you  
> want it to be documented would help the community to then start  
> contributing as the code goes through its normal changes and churning.
>
> Just a thought ...
>
> -Steve W.
>
> Paul Spencer wrote:
>> Reuven,
>> you are absolutely correct and your comments welcome.  I'm not  
>> sure  that documentation would only take a couple of hours,  
>> though ;)  And  since I don't get paid to do it, its not that high  
>> on my list.   However, that being said, I have been thinking about  
>> this for quite a  while.  I'm going to try to get a wiki set up  
>> for ka-Map as that  would be the main source of obtaining  
>> documentation and posting FAQ  and their answers.
>> Thanks for prodding me on this.  I promise to try to do something   
>> about it :)
>> One thing that would really help me in putting this together is  
>> to  have others share their experiences on developing  
>> applications, where  they had problems and what types of things  
>> they would like to do.   That would help me focus on providing the  
>> most useful documentation  first.
>> Cheers
>> Paul
>> On 17-Dec-05, at 5:28 AM, Reuven Levitt wrote:
>>> Hi Everyone,
>>>
>>> I am not one of the Ka-Maps developers, but am active on several   
>>> other open source projects. I have used Ka-Maps, and feel that  
>>> it  is an amazing project, and a lot of hard work has clearly  
>>> been put  into it.
>>>
>>> I would like to make a small suggestion that may push the Ka-Map   
>>> project forward tremendously.  One of the biggest shortcomings  
>>> of  many open source projects, and therefore the limitation on  
>>> people  adopting and using the product is documentation.   
>>> Unfortunately Ka- Maps is no exception.  There is very very  
>>> little documentation, no  Wiki available to add documentation too  
>>> and no FAQ.  In reality   writing a simple documentation that  
>>> outlines the functions  available would take a lead developer  
>>> only a couple of hours of  work, and would then provide a good  
>>> seed for growth to allow other  developers to help push the  
>>> project forward.
>>>
>>> Hope this comment is taken in the light it is ! intended, as   
>>> constructive criticism.
>>>
>>> Thanks for all the hard work,
>>> Great job on a fantastic product,
>>>
>>> Reuven.
>>> _______________________________________________
>>> ka-Map-users mailing list
>>> ka-Map-users at lists.maptools.org
>>> http://lists.maptools.org/mailman/listinfo/ka-map-users
>> +-----------------------------------------------------------------+
>> |Paul Spencer                           pspencer at dmsolutions.ca   |
>> +-----------------------------------------------------------------+
>> |Applications & Software Development                              |
>> |DM Solutions Group Inc                 http://www.dmsolutions.ca/|
>> +-----------------------------------------------------------------+
>> _______________________________________________
>> ka-Map-users mailing list
>> ka-Map-users at lists.maptools.org
>> http://lists.maptools.org/mailman/listinfo/ka-map-users
>
>

+-----------------------------------------------------------------+
|Paul Spencer                           pspencer at dmsolutions.ca   |
+-----------------------------------------------------------------+
|Applications & Software Development                              |
|DM Solutions Group Inc                 http://www.dmsolutions.ca/|
+-----------------------------------------------------------------+