Documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
19 messages Options
Reply | Threaded
Open this post in threaded view
|

Documentation

keithy

Hi,

where do we put documentation these days?

Keith



Reply | Threaded
Open this post in threaded view
|

Re: Documentation

timrowledge


> On 17-08-2018, at 1:19 PM, Keith <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
Oxymorons: Clearly misunderstood



Reply | Threaded
Open this post in threaded view
|

Re: Documentation

KenCausey
On 8/17/2018 4:40 PM, tim Rowledge wrote:
>
>> On 17-08-2018, at 1:19 PM, Keith <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
>> Oxymorons: Clearly misunderstood
>>
>>
>>


Reply | Threaded
Open this post in threaded view
|

Re: Documentation

timrowledge


> On 17-08-2018, at 3:42 PM, Ken Causey <[hidden email]> wrote:
>
> On 8/17/2018 4:40 PM, tim Rowledge wrote:
>>
>>> On 17-08-2018, at 1:19 PM, Keith <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: CM: Circulate Memory



Reply | Threaded
Open this post in threaded view
|

Re: Documentation

David T. Lewis
In reply to this post by KenCausey
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 <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Karl Ramberg
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 <[hidden email]> 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 <[hidden email]> 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




Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Eliot Miranda-2


On Aug 18, 2018, at 6:02 AM, karl ramberg <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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





Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Eliot Miranda-2
In reply to this post by KenCausey


> On Aug 17, 2018, at 3:42 PM, Ken Causey <[hidden email]> wrote:
>
>> On 8/17/2018 4:40 PM, tim Rowledge wrote:
>>
>>> On 17-08-2018, at 1:19 PM, Keith <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
>>> Oxymorons: Clearly misunderstood
>>>
>>>
>>>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Chris Muller-3
In reply to this post by Eliot Miranda-2
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 <[hidden email]> wrote:

>
>
> On Aug 18, 2018, at 6:02 AM, karl ramberg <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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
>>
>>
>
>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

timrowledge
In reply to this post by Eliot Miranda-2


> On 18-08-2018, at 7:07 AM, Eliot Miranda <[hidden email]> wrote:
>
>
>
> On Aug 18, 2018, at 6:02 AM, karl ramberg <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
Useful random insult:- Teflon brain -- nothing sticks.



Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Eliot Miranda-2
In reply to this post by Chris Muller-3
Hi Chris,

> On Aug 18, 2018, at 10:12 AM, Chris Muller <[hidden email]> 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 <[hidden email]> wrote:
>>
>>
>> On Aug 18, 2018, at 6:02 AM, karl ramberg <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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
>>>
>>>
>>
>>
>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Eliot Miranda-2
In reply to this post by timrowledge
Hi Tim,


> On Aug 18, 2018, at 10:23 AM, tim Rowledge <[hidden email]> wrote:
>
>
>
>> On 18-08-2018, at 7:07 AM, Eliot Miranda <[hidden email]> wrote:
>>
>>
>>
>>> On Aug 18, 2018, at 6:02 AM, karl ramberg <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
> Useful random insult:- Teflon brain -- nothing sticks.
>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Eliot Miranda-2
Hi Tim,


> On Aug 18, 2018, at 10:42 AM, Eliot Miranda <[hidden email]> wrote:
>
> Hi Tim,
>
>
>> On Aug 18, 2018, at 10:23 AM, tim Rowledge <[hidden email]> wrote:
>>
>>
>>
>>> On 18-08-2018, at 7:07 AM, Eliot Miranda <[hidden email]> wrote:
>>>
>>>
>>>
>>>> On Aug 18, 2018, at 6:02 AM, karl ramberg <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
>> Useful random insult:- Teflon brain -- nothing sticks.
>>
>>
>>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

timrowledge


> On 18-08-2018, at 10:45 AM, Eliot Miranda <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
Every bug you find is the last one.



Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Chris Muller-3
In reply to this post by Eliot Miranda-2
>> 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

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Squeak - Dev mailing list
In reply to this post by timrowledge
I think SqueakMap could catalog documentation wherever it resides.

Ken G. Brown

> On Aug 18, 2018, at 11:53, tim Rowledge <[hidden email]> wrote:
>
>
>
>> On 18-08-2018, at 10:45 AM, Eliot Miranda <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
> Every bug you find is the last one.
>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

keithy

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



Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Hannes Hirzel
In reply to this post by Chris Muller-3
On 8/18/18, Chris Muller <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Hannes Hirzel
In reply to this post by Squeak - Dev mailing list
On 8/18/18, Ken Brown via Squeak-dev
<[hidden email]> 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