[Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

tim Rowledge tim at rowledge.org
Fri Apr 6 20:41:05 UTC 2007


On 6-Apr-07, at 1:27 PM, Tim Johnson wrote:

>> I agree with Tim and Matt that using comments would be great way to
>> go, with one caveat :)
>>
>> The biggest frustration with using comments is that there is no good
>> "starting place" for a given class category. For example, go browse
>> the Seaside classes and categories and figure out where one should
>> start. You can repeat this exercise for any number of categories. I
>> propose that we we add a documentation attribute to the PackageInfo
>> stuff, so there is a category level documentation spot, with links to
>> the appropriate class comments.
>>
>> Any thoughts?
>
> When I am trying to figure out which class in a class category is a  
> good
> starting point, I look at which class is the lowest in the inheritance
> chain...

This problem of 'where to start' is why I pointed out the cross- 
linking capability.

For each class involved in a package or subsystem, simply add a link  
back to the 'main' class. Put the major documentation there. For  
methods involved in a package that doesn't really involve most of the  
class, put the link in the method comment. Classes involved in many  
packages would need somewhat longer and more developed comments than  
we are used to. URL links would allow pointing out to more  
sophisticated doc on the web somewhere, in a form that is perhaps  
more easily updated

tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Porting is such sweet sorrow





More information about the Squeak-dev mailing list