Proposing class Category README or HOWTO for easy access to documentation within the system
Hi All,
Stefan Ducasse replied to me regarding my synapsis of the CMakeVMaker code.
Igor created all the logic of the CMakeGenerator but I guess that he did not add good class comments so I thought that it would be great if you can add the comment to a class so that it is not lost. Information external to classes is often lost.
And I agree with him.
In Linux/Open Source world, are the conventions of README and HOWTO. I propose that Squeak adopt two class categories for developers to add easy access to documentation on subsystems in the README category and quick howto_foo_a_bar classes in the HOWTO category.
I know we have the web, and there is a Help system, but I find the Help system a bit clunky to use and breaking from Squeak environment to Web for information breaks the flow.
A recent example of where this proposal would come in handy is the recent discussion about reviving Tweak for Squeak 4.5/4.6. The time investment to get up to speed is vastly increased by having to hunt for information.
just my .02
cheers.
tty
On Thu, Jun 12, 2014 at 11:29 AM, gettimothy gettimothy@zoho.com wrote:
Hi All,
Stefan Ducasse replied to me regarding my synapsis of the CMakeVMaker code.
Igor created all the logic of the CMakeGenerator but I guess that he did not add good class comments so I thought that it would be great if you can add the comment to a class so that it is not lost.* Information external to classes is often lost.*
And I agree with him.
So do I. Personally I like class comments. I don't want to look for methods that contain help text. The convention there is to provide an "examples" category containing example methods. So please let's /not/ add another category or convention for including documentation in methods, categories or classes. There are also tests. But as for externally readable help or more general browsable help I agree, Wikis and the Help system are good places. The most important thing is knowing where these are, so putting options on the screen menu or the menu bar is really really important.
However, copying Pharo mad making the lack of a class comment in the browser noticeable (colouring the " ? " button red when there's no class comment for example) is a really good idea.
In Linux/Open Source world, are the conventions of README and HOWTO. I propose that Squeak adopt two class categories for developers to add easy access to documentation on subsystems in the README category and quick howto_foo_a_bar classes in the HOWTO category.
I know we have the web, and there is a Help system, but I find the Help system a bit clunky to use and breaking from Squeak environment to Web for information breaks the flow.
A recent example of where this proposal would come in handy is the recent discussion about reviving Tweak for Squeak 4.5/4.6. The time investment to get up to speed is vastly increased by having to hunt for information.
just my .02
cheers.
tty
On 13-06-2014, at 9:37 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
So do I. Personally I like class comments. I don't want to look for methods that contain help text.
Me too.
There’s nothing to prevent an extension of the HelpBrowser to have it use the contents of class comments and/or other sources of text, which would make it really easy for people to add content.
We probably don’t want to clutter the image with large strings (there’s already too many) and class comments get stored in the changes which is a sensible place to have them. It shouldn’t be difficult to make any other local documentation live in the same place(s) - we only need a convention on the method name(s) to allow specified method comments to be sucked in. When online it shouldn’t be beyond us to suck in swiki page content.
But the mechanism isn’t anywhere near as important as the content. Lots of us are capable of the programming for the mechanism but fewer have the writing talent to produce good documentation - let alone the time.
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim The Static Typing Philosophy: Make it fast. Make it right. Make it run.
> So do I. Personally I like class comments. I don't want to look for methods that contain help text.
Me too.
There’s nothing to prevent an extension of the HelpBrowser to have it use the contents of class comments and/or other sources of text, which would make it really easy for people to add content.
We probably don’t want to clutter the image with large strings (there’s already too many) and class comments get stored in the changes which is a sensible place to have them. It shouldn’t be difficult to make any other local documentation live in the same place(s) - we only need a convention on the method name(s) to allow specified method comments to be sucked in. When online it shouldn’t be beyond us to suck in swiki page content.
But the mechanism isn’t anywhere near as important as the content. Lots of us are capable of the programming for the mechanism but fewer have the writing talent to produce good documentation - let alone the time.
Sounds good.
Help Browser it is.
Chris is doing work to incorporate Wiki with it so it stands to reason that HOWTOS (besides being in the examples category and/or class comments) should reside there.
I have seen the pharo class comments integrated into help and it is a good improvement.
Personally, I am going to treat Help Documentation as I do Tests--something to implement as I code.
Thanks for the consideration.
tty
You can doIt HelpBrowser openOn: SystemReference
That will open a HelpBrowser on all class comments.
Karl
On Fri, Jun 13, 2014 at 6:50 PM, tim Rowledge tim@rowledge.org wrote:
On 13-06-2014, at 9:37 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
So do I. Personally I like class comments. I don't want to look for
methods that contain help text.
Me too.
There’s nothing to prevent an extension of the HelpBrowser to have it use the contents of class comments and/or other sources of text, which would make it really easy for people to add content.
We probably don’t want to clutter the image with large strings (there’s already too many) and class comments get stored in the changes which is a sensible place to have them. It shouldn’t be difficult to make any other local documentation live in the same place(s) - we only need a convention on the method name(s) to allow specified method comments to be sucked in. When online it shouldn’t be beyond us to suck in swiki page content.
But the mechanism isn’t anywhere near as important as the content. Lots of us are capable of the programming for the mechanism but fewer have the writing talent to produce good documentation - let alone the time.
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim The Static Typing Philosophy: Make it fast. Make it right. Make it run.
You can doIt HelpBrowser openOn: SystemReference That will open a HelpBrowser on all class comments.
Karl
Thx.
very useful.
tty
vm-dev@lists.squeakfoundation.org
-
Eliot Miranda -
gettimothy -
karl ramberg -
tim Rowledge