On 17-08-2018, at 1:19 PM, Keith keithy@consultant.com wrote:
Hi,
where do we put documentation these days?
Excellent question. Several answers -
A method ought to be commented as to what it is *meant* to do. That is not always what the code actually does, for example during early stages of development. It would be nice if the comment explained any known limitations or likely error conditions.
A class should be commented to explain its intent, along with what ivars are used for and maybe even the sources for any interesting algorithms used. Mentioning other related classes and how they help might be nice.
Add a page to the HelpBrowser system. Take a look at the Help browser (main menu -> Help) and look at the 'Help on Help' section, in particular the 'Implementation' part. This is a good way to document something about systems and applications rather than the classes and code implementing them. We need a *lot* more help pages.
Add a page or ten to the swiki. This is a good place to be more expansive since it doesn't take any space in the image or sources. And you can include pictures which we don't seem to be able to do in the HelpBrowser (yet).
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Oxymorons: Clearly misunderstood
On 8/17/2018 4:40 PM, tim Rowledge wrote:
On 17-08-2018, at 1:19 PM, Keith keithy@consultant.com wrote:
Hi,
where do we put documentation these days?
While we are on this subject has anyone looked into adding documentation at the category and/or package level? As someone who is barely paying attention anymore but occasionally gets an itch to do some work in Squeak it is really difficult to figure out what is already on hand in an image at a high level, higher than per-class.
Excellent question. Several answers -
A method ought to be commented as to what it is *meant* to do. That is not always what the code actually does, for example during early stages of development. It would be nice if the comment explained any known limitations or likely error conditions.
A class should be commented to explain its intent, along with what ivars are used for and maybe even the sources for any interesting algorithms used. Mentioning other related classes and how they help might be nice.
Add a page to the HelpBrowser system. Take a look at the Help browser (main menu -> Help) and look at the 'Help on Help' section, in particular the 'Implementation' part. This is a good way to document something about systems and applications rather than the classes and code implementing them. We need a *lot* more help pages.
Add a page or ten to the swiki. This is a good place to be more expansive since it doesn't take any space in the image or sources. And you can include pictures which we don't seem to be able to do in the HelpBrowser (yet).
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Oxymorons: Clearly misunderstood
On 17-08-2018, at 3:42 PM, Ken Causey klcausey@gmail.com wrote:
On 8/17/2018 4:40 PM, tim Rowledge wrote:
On 17-08-2018, at 1:19 PM, Keith keithy@consultant.com wrote:
Hi,
where do we put documentation these days?
While we are on this subject has anyone looked into adding documentation at the category and/or package level? As someone who is barely paying attention anymore but occasionally gets an itch to do some work in Squeak it is really difficult to figure out what is already on hand in an image at a high level, higher than per-class.
At the category level I don't think it makes a huge amount of sense since they're just organisational niceties. Packages - in the sense of loadable applications or library add-ons - should of course have documentation within the package file(s) that can be read from squeaksource/monticello/etc in order to let you decide whether to load it or not. Swiki pages are good for that too. And then include Help Browser content within the package so there is something in the image once loaded - which of course ought to point to any swiki or other online info. And we really ought to be able to use the platform mechanism for opening a browser at the referenced page.
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Strange OpCodes: CM: Circulate Memory
On Fri, Aug 17, 2018 at 05:42:24PM -0500, Ken Causey wrote:
On 8/17/2018 4:40 PM, tim Rowledge wrote:
On 17-08-2018, at 1:19 PM, Keith keithy@consultant.com wrote:
Hi,
where do we put documentation these days?
While we are on this subject has anyone looked into adding documentation at the category and/or package level? As someone who is barely paying attention anymore but occasionally gets an itch to do some work in Squeak it is really difficult to figure out what is already on hand in an image at a high level, higher than per-class.
I do not know of anything that has been done in this regard, but on the face of it I cannot think of any reason that classes and methods should be objects, while method categories and class categories are just labels.
Maybe somebody should do something about that.
Dave
WebClient and WebServer are the only packages that have real HelpBrowser documentation for both reference and use. It would be nice to have similar documentation for other classes. But the framework is pretty much there
Best, Karl
On Sat, Aug 18, 2018 at 12:58 AM David T. Lewis lewis@mail.msen.com wrote:
On Fri, Aug 17, 2018 at 05:42:24PM -0500, Ken Causey wrote:
On 8/17/2018 4:40 PM, tim Rowledge wrote:
On 17-08-2018, at 1:19 PM, Keith keithy@consultant.com wrote:
Hi,
where do we put documentation these days?
While we are on this subject has anyone looked into adding documentation at the category and/or package level? As someone who is barely paying attention anymore but occasionally gets an itch to do some work in Squeak it is really difficult to figure out what is already on hand in an image at a high level, higher than per-class.
I do not know of anything that has been done in this regard, but on the face of it I cannot think of any reason that classes and methods should be objects, while method categories and class categories are just labels.
Maybe somebody should do something about that.
Dave
On Aug 18, 2018, at 6:02 AM, karl ramberg karlramberg@gmail.com wrote:
WebClient and WebServer are the only packages that have real HelpBrowser documentation for both reference and use. It would be nice to have similar documentation for other classes. But the framework is pretty much there
+1000. But this should be *in each package*. Pharo just introduced a PackageModel or some such off which one can hang various package attributes. Each package can have a subclass of this named <PackageName>PackageModel (eg KernelPackageModel). The most basic thing is something that describes what the package does. Wonderful things like Nebraska remain underused because it is not described briefly and hence is unknown to most users. Maybe this can be a focus for the next release. Let’s get 5.2 out ASAP and then aim for 6.0 to be an approachable release.
Best, Karl
On Sat, Aug 18, 2018 at 12:58 AM David T. Lewis lewis@mail.msen.com wrote: On Fri, Aug 17, 2018 at 05:42:24PM -0500, Ken Causey wrote:
On 8/17/2018 4:40 PM, tim Rowledge wrote:
On 17-08-2018, at 1:19 PM, Keith keithy@consultant.com wrote:
Hi,
where do we put documentation these days?
While we are on this subject has anyone looked into adding documentation at the category and/or package level? As someone who is barely paying attention anymore but occasionally gets an itch to do some work in Squeak it is really difficult to figure out what is already on hand in an image at a high level, higher than per-class.
I do not know of anything that has been done in this regard, but on the face of it I cannot think of any reason that classes and methods should be objects, while method categories and class categories are just labels.
Maybe somebody should do something about that.
Dave
We've had PackageInfo for eons which I've subclassed in my own apps forever to override several documentative as well as functional methods in there. But there was never any interest (in fact, resistance!) in doing that in this community. Glad to see y'all finally opening up to the idea, but I see no reason to have a "PackageInfo" AND a "PackageModel".
But do we REALLY want to bloat image memory with a bunch of "documentation" that no one will ever read and will be out of date within one release? We can't keep our existing documentation (wiki, etc.) updated, I'd suggest seeing if we can actually commit to cleaning that up before harming the image with new kinds of documentation.
On Sat, Aug 18, 2018 at 9:07 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
On Aug 18, 2018, at 6:02 AM, karl ramberg karlramberg@gmail.com wrote:
WebClient and WebServer are the only packages that have real HelpBrowser documentation for both reference and use. It would be nice to have similar documentation for other classes. But the framework is pretty much there
+1000. But this should be *in each package*. Pharo just introduced a PackageModel or some such off which one can hang various package attributes. Each package can have a subclass of this named <PackageName>PackageModel (eg KernelPackageModel). The most basic thing is something that describes what the package does. Wonderful things like Nebraska remain underused because it is not described briefly and hence is unknown to most users. Maybe this can be a focus for the next release. Let’s get 5.2 out ASAP and then aim for 6.0 to be an approachable release.
Best, Karl
On Sat, Aug 18, 2018 at 12:58 AM David T. Lewis lewis@mail.msen.com wrote:
On Fri, Aug 17, 2018 at 05:42:24PM -0500, Ken Causey wrote:
On 8/17/2018 4:40 PM, tim Rowledge wrote:
On 17-08-2018, at 1:19 PM, Keith keithy@consultant.com wrote:
Hi,
where do we put documentation these days?
While we are on this subject has anyone looked into adding documentation at the category and/or package level? As someone who is barely paying attention anymore but occasionally gets an itch to do some work in Squeak it is really difficult to figure out what is already on hand in an image at a high level, higher than per-class.
I do not know of anything that has been done in this regard, but on the face of it I cannot think of any reason that classes and methods should be objects, while method categories and class categories are just labels.
Maybe somebody should do something about that.
Dave
Hi Chris,
On Aug 18, 2018, at 10:12 AM, Chris Muller asqueaker@gmail.com wrote:
We've had PackageInfo for eons which I've subclassed in my own apps forever to override several documentative as well as functional methods in there. But there was never any interest (in fact, resistance!) in doing that in this community. Glad to see y'all finally opening up to the idea, but I see no reason to have a "PackageInfo" AND a "PackageModel".
Doh! Of course. Forgive me. So per-package subclasses of PackageInfo or extent PackageInfo and store instances? I expect using the class will be less problematic.
But do we REALLY want to bloat image memory with a bunch of "documentation" that no one will ever read and will be out of date within one release? We can't keep our existing documentation (wiki, etc.) updated, I'd suggest seeing if we can actually commit to cleaning that up before harming the image with new kinds of documentation.
The thing is about a per package class is that it’s not separate and is easy to keep up to date. If there’s good tool support (eg a help browser like system for organizing documentation & examples) then there’s incentive to keep it up to date.
And these things should be trivial too strip for deployment if one wants.
On Sat, Aug 18, 2018 at 9:07 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
On Aug 18, 2018, at 6:02 AM, karl ramberg karlramberg@gmail.com wrote:
WebClient and WebServer are the only packages that have real HelpBrowser documentation for both reference and use. It would be nice to have similar documentation for other classes. But the framework is pretty much there
+1000. But this should be *in each package*. Pharo just introduced a PackageModel or some such off which one can hang various package attributes. Each package can have a subclass of this named <PackageName>PackageModel (eg KernelPackageModel). The most basic thing is something that describes what the package does. Wonderful things like Nebraska remain underused because it is not described briefly and hence is unknown to most users. Maybe this can be a focus for the next release. Let’s get 5.2 out ASAP and then aim for 6.0 to be an approachable release.
Best, Karl
On Sat, Aug 18, 2018 at 12:58 AM David T. Lewis lewis@mail.msen.com wrote:
On Fri, Aug 17, 2018 at 05:42:24PM -0500, Ken Causey wrote:
On 8/17/2018 4:40 PM, tim Rowledge wrote:
On 17-08-2018, at 1:19 PM, Keith keithy@consultant.com wrote:
Hi,
where do we put documentation these days?
While we are on this subject has anyone looked into adding documentation at the category and/or package level? As someone who is barely paying attention anymore but occasionally gets an itch to do some work in Squeak it is really difficult to figure out what is already on hand in an image at a high level, higher than per-class.
I do not know of anything that has been done in this regard, but on the face of it I cannot think of any reason that classes and methods should be objects, while method categories and class categories are just labels.
Maybe somebody should do something about that.
Dave
But do we REALLY want to bloat image memory with a bunch of "documentation" that no one will ever read and will be out of date within one release? We can't keep our existing documentation (wiki, etc.) updated, I'd suggest seeing if we can actually commit to cleaning that up before harming the image with new kinds of documentation.
The thing is about a per package class is that it’s not separate and is easy to keep up to date. If there’s good tool support (eg a help browser like system for organizing documentation & examples) then there’s incentive to keep it up to date.
That seems like it would be the case, but in my own practice of doing it, my subclasses ended up as much out-of-date as various other class and method comments throughout the system. I think your VMMaker example is illustrative of that it really boils down to the "economy" of documentation. Whenever we're writing documentation, we're not only not writing or clarifying code, but actually creating an entirely new artifact that must be physically maintained in the future -- "another mouth to feed". I'm sure discipline is a factor too, but I think this economy is a large reason why even in-image documentation is always behind the code.
And these things should be trivial too strip for deployment if one wants.
True, but it's not only about RAM though, but other dimensions of impact like "reader fatigue". Anytime documentation is dilute or repeats what's already very obvious, it's value becomes immediately discounted by the user. They start skimming comments instead of seeing them as "gold nuggets" of pure value. Pretty soon, they've trained themselves to ignore them entirely, and suddenly they're not getting maintained either.
Documentation is and should be an art. The goal is not "documentation", but clarity for users. When something is small or simple, there is already a huge headstart on clarity, which is why in-image documentation should only be very minimal and _additive_, never duplicate.
Class comments, for example, should not list out their instVars with descriptions that are either obvious or could/should otherwise be found in the accessors. Instead provide only what's not obvious -- perhaps a brief high-level descriptions that summarizes its responsibility and overall implementation in a sentence or two. It should "decorate" the code elements by enhancing its readability, not replacing it. Anything more quickly becomes subtractive -- future maintenance, reader fatigue, RAM, etc. It's a balancing act.
Best, Chris
On 8/18/18, Chris Muller asqueaker@gmail.com wrote:
Class comments, for example, should not list out their instVars with descriptions that are either obvious or could/should otherwise be found in the accessors. Instead provide only what's not obvious -- perhaps a brief high-level descriptions that summarizes its responsibility and overall implementation in a sentence or two. It should "decorate" the code elements by enhancing its readability, not replacing it. Anything more quickly becomes subtractive -- future maintenance, reader fatigue, RAM, etc. It's a balancing act.
+1 And there are a lot of classes where even a basic explanations of instance variables which are not obvious are missing. So contributions in the inbox are welcome.
Suggestion: Let's focus on a small group of packages. The ones which are of current interest because of commits for other purposes. The debugger at the moment for example.
--Hannes
On 18-08-2018, at 7:07 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
On Aug 18, 2018, at 6:02 AM, karl ramberg karlramberg@gmail.com wrote:
WebClient and WebServer are the only packages that have real HelpBrowser documentation for both reference and use. It would be nice to have similar documentation for other classes. But the framework is pretty much there
+1000. But this should be *in each package*.
Obviously any package can include content intended for the Help Browser system. That content can be of quite a variety of forms, ranging from actual in-image strings to swiki page content that is loaded at need. If it isn't already there I don't imagine it would be hard to arrange for the content to be stored in the comments of otherwise innocuous methods and thus effectively stored in the changes file.
The key issue is *not* any worry about how to store the stuff. We're a bunch of programming gods - we can make that stuff work any way we want. It's creating useful, meaningful, reliable, up to date helpful content that actually helps people. *That* is hard work.
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Teflon brain -- nothing sticks.
Hi Tim,
On Aug 18, 2018, at 10:23 AM, tim Rowledge tim@rowledge.org wrote:
On 18-08-2018, at 7:07 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
On Aug 18, 2018, at 6:02 AM, karl ramberg karlramberg@gmail.com wrote:
WebClient and WebServer are the only packages that have real HelpBrowser documentation for both reference and use. It would be nice to have similar documentation for other classes. But the framework is pretty much there
+1000. But this should be *in each package*.
Obviously any package can include content intended for the Help Browser system. That content can be of quite a variety of forms, ranging from actual in-image strings to swiki page content that is loaded at need. If it isn't already there I don't imagine it would be hard to arrange for the content to be stored in the comments of otherwise innocuous methods and thus effectively stored in the changes file.
The key issue is *not* any worry about how to store the stuff. We're a bunch of programming gods - we can make that stuff work any way we want. It's creating useful, meaningful, reliable, up to date helpful content that actually helps people. *That* is hard work.
I’m not sure I agree. I’ve written a fair ammount of stuff on VMMaker over the years, in blog posts, email messages, class comments, papers, presentations and Quora answers. The main issues have been being able to conveniently combine editable/edited text and image, and making this conveniently accessible to an audience. Right now I like Quora because it is a place where different programs granting communities meet.
I would have loved to write my blog posts in image and have them included in VMMaker, accessible through some tool like the Help Browser. Conceivably they could be kept more up to date that way. They could even have been exported auto magically to the web for access by a wider audience but I lacked the vision and foresight to take this approach and now I have lots of disparate information with little hope of findings mg the time to pull it together. And the result is a mess for the person who wants the use VMMaker. Instead of pointing that person at a tool which includes documentation, executable examples and URLs of relevant papers, the person n is directed to a slew of disconnected, partial and fundamentally incoherent documents in a wide variety of places. We have the technology to build a suitable tool. Can we find the coherence to design, implement and use it?
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Teflon brain -- nothing sticks.
Hi Tim,
On Aug 18, 2018, at 10:42 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
Hi Tim,
On Aug 18, 2018, at 10:23 AM, tim Rowledge tim@rowledge.org wrote:
On 18-08-2018, at 7:07 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
On Aug 18, 2018, at 6:02 AM, karl ramberg karlramberg@gmail.com wrote:
WebClient and WebServer are the only packages that have real HelpBrowser documentation for both reference and use. It would be nice to have similar documentation for other classes. But the framework is pretty much there
+1000. But this should be *in each package*.
Obviously any package can include content intended for the Help Browser system. That content can be of quite a variety of forms, ranging from actual in-image strings to swiki page content that is loaded at need. If it isn't already there I don't imagine it would be hard to arrange for the content to be stored in the comments of otherwise innocuous methods and thus effectively stored in the changes file.
The key issue is *not* any worry about how to store the stuff. We're a bunch of programming gods - we can make that stuff work any way we want. It's creating useful, meaningful, reliable, up to date helpful content that actually helps people. *That* is hard work.
On rereading your message I realise we /do/ agree. Apologies, I’ve been up until 3am yesterday and today finishing a paper with Clément and others and I’m a bit foggy. So please strike the “I’m not sure I agree” from my message; I shouldn’t have written that.
I’m not sure I agree. I’ve written a fair ammount of stuff on VMMaker over the years, in blog posts, email messages, class comments, papers, presentations and Quora answers. The main issues have been being able to conveniently combine editable/edited text and image, and making this conveniently accessible to an audience. Right now I like Quora because it is a place where different programs granting communities meet.
I would have loved to write my blog posts in image and have them included in VMMaker, accessible through some tool like the Help Browser. Conceivably they could be kept more up to date that way. They could even have been exported auto magically to the web for access by a wider audience but I lacked the vision and foresight to take this approach and now I have lots of disparate information with little hope of findings mg the time to pull it together. And the result is a mess for the person who wants the use VMMaker. Instead of pointing that person at a tool which includes documentation, executable examples and URLs of relevant papers, the person n is directed to a slew of disconnected, partial and fundamentally incoherent documents in a wide variety of places. We have the technology to build a suitable tool. Can we find the coherence to design, implement and use it?
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Teflon brain -- nothing sticks.
On 18-08-2018, at 10:45 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
I’ve written a fair ammount of stuff on VMMaker over the years, in blog posts, email messages, class comments, papers, presentations and Quora answers. The main issues have been being able to conveniently combine editable/edited text and image, and making this conveniently accessible to an audience. Right now I like Quora because it is a place where different programs granting communities meet.
I would have loved to write my blog posts in image and have them included in VMMaker, accessible through some tool like the Help Browser. Conceivably they could be kept more up to date that way. They could even have been exported auto magically to the web for access by a wider audience but I lacked the vision and foresight to take this approach and now I have lots of disparate information with little hope of findings mg the time to pull it together. And the result is a mess for the person who wants the use VMMaker. Instead of pointing that person at a tool which includes documentation, executable examples and URLs of relevant papers, the person n is directed to a slew of disconnected, partial and fundamentally incoherent documents in a wide variety of places. We have the technology to build a suitable tool. Can we find the coherence to design, implement and use it?
I'm pretty sure we could find a way to integrate the various repositories you and others have used; obviously one way to tackle part of the complexity is to decide on a smaller number of places and move any content currently in other places. For a lot of useful info a simple copy&paste would be sufficient and who knows - it might even prompt some editing & rewriting.
The Help Browser does have a bunch of code to suck in swiki content and I suspect reading from Quora or StackOverflow etc would be doable. The nice thing about swiki content is that we can if necessary update the swiki to help with this. (Um, we do still have the code for the swiki don't we?)
Another option would be to make that 'fire up the web' stuff work and have much help/doc linked to that way. Negligible space usage in-image, swiki/quora/geobook/faceworlds content handled. I'll admit I'd prefer to see us use all that clever book/presentation stuff that Alan has used so well for this but I'd need some .... documentation. And I think it might be made a bit easier to use for the general case too.
As you say, coherence and commitment and time to meet that commitment are the items in short supply.
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Every bug you find is the last one.
I think SqueakMap could catalog documentation wherever it resides.
Ken G. Brown
On Aug 18, 2018, at 11:53, tim Rowledge tim@rowledge.org wrote:
On 18-08-2018, at 10:45 AM, Eliot Miranda eliot.miranda@gmail.com wrote:
I’ve written a fair ammount of stuff on VMMaker over the years, in blog posts, email messages, class comments, papers, presentations and Quora answers. The main issues have been being able to conveniently combine editable/edited text and image, and making this conveniently accessible to an audience. Right now I like Quora because it is a place where different programs granting communities meet.
I would have loved to write my blog posts in image and have them included in VMMaker, accessible through some tool like the Help Browser. Conceivably they could be kept more up to date that way. They could even have been exported auto magically to the web for access by a wider audience but I lacked the vision and foresight to take this approach and now I have lots of disparate information with little hope of findings mg the time to pull it together. And the result is a mess for the person who wants the use VMMaker. Instead of pointing that person at a tool which includes documentation, executable examples and URLs of relevant papers, the person n is directed to a slew of disconnected, partial and fundamentally incoherent documents in a wide variety of places. We have the technology to build a suitable tool. Can we find the coherence to design, implement and use it?
I'm pretty sure we could find a way to integrate the various repositories you and others have used; obviously one way to tackle part of the complexity is to decide on a smaller number of places and move any content currently in other places. For a lot of useful info a simple copy&paste would be sufficient and who knows - it might even prompt some editing & rewriting.
The Help Browser does have a bunch of code to suck in swiki content and I suspect reading from Quora or StackOverflow etc would be doable. The nice thing about swiki content is that we can if necessary update the swiki to help with this. (Um, we do still have the code for the swiki don't we?)
Another option would be to make that 'fire up the web' stuff work and have much help/doc linked to that way. Negligible space usage in-image, swiki/quora/geobook/faceworlds content handled. I'll admit I'd prefer to see us use all that clever book/presentation stuff that Alan has used so well for this but I'd need some .... documentation. And I think it might be made a bit easier to use for the general case too.
As you say, coherence and commitment and time to meet that commitment are the items in short supply.
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Every bug you find is the last one.
In the OP, I was thinking about Online documentation, to know and understand what I might be loading before it makes it into the image. I was also thinking about PR, many projects get a lot of visibility from being on GitHub, (not that I like GitHub that much).
Keith
On 8/18/18, Ken Brown via Squeak-dev squeak-dev@lists.squeakfoundation.org wrote:
I think SqueakMap could catalog documentation wherever it resides.
Ken G. Brown
Yes, HelpSystem extensions
Another easy thing to access is the wiki. Access to it is available from within the Squeak HelpSystem.
--Hannes
On Aug 17, 2018, at 3:42 PM, Ken Causey klcausey@gmail.com wrote:
On 8/17/2018 4:40 PM, tim Rowledge wrote:
On 17-08-2018, at 1:19 PM, Keith keithy@consultant.com wrote:
Hi,
where do we put documentation these days?
While we are on this subject has anyone looked into adding documentation at the category and/or package level? As someone who is barely paying attention anymore but occasionally gets an itch to do some work in Squeak it is really difficult to figure out what is already on hand in an image at a high level, higher than per-class.
+1
Excellent question. Several answers -
A method ought to be commented as to what it is *meant* to do. That is not always what the code actually does, for example during early stages of development. It would be nice if the comment explained any known limitations or likely error conditions.
A class should be commented to explain its intent, along with what ivars are used for and maybe even the sources for any interesting algorithms used. Mentioning other related classes and how they help might be nice.
Add a page to the HelpBrowser system. Take a look at the Help browser (main menu -> Help) and look at the 'Help on Help' section, in particular the 'Implementation' part. This is a good way to document something about systems and applications rather than the classes and code implementing them. We need a *lot* more help pages.
Add a page or ten to the swiki. This is a good place to be more expansive since it doesn't take any space in the image or sources. And you can include pictures which we don't seem to be able to do in the HelpBrowser (yet).
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Oxymorons: Clearly misunderstood
squeak-dev@lists.squeakfoundation.org
-
Chris Muller -
David T. Lewis -
Eliot Miranda -
H. Hirzel -
karl ramberg -
Keith -
Ken Brown -
Ken Causey -
tim Rowledge