[squeak-dev] Documentation

tim Rowledge tim at rowledge.org
Sat Aug 18 18:53:17 UTC 2018



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




More information about the Squeak-dev mailing list