[squeak-dev] Documentation

Eliot Miranda eliot.miranda at gmail.com
Sat Aug 18 17:45:55 UTC 2018


Hi Tim,


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


More information about the Squeak-dev mailing list