[squeak-dev] self error: 'comment only'

gettimothy gettimothy at zoho.com
Mon Mar 23 11:18:23 UTC 2020


This is a great discussion.

Regarding Eliot's and Subbu's comments


---- On Mon, 23 Mar 2020 01:23:33 -0400 kksubbu.ml at gmail.com wrote ----


On 23/03/20 3:29 AM, Eliot Miranda wrote:
> What I think Subbu’s analysis and this scaling problem implies is
> that the Help Browser is a great central location to go to to find
> documentation, but the Help Browser will be better if it is able to
> display class comments and documentation methods as well as its own
> help pages. My vote is to make the Help Browser multi-modal and
> about indexing tool for accessing help and documentation in as many
> turns as possible, including pointers to web pages and videos.



In short, help topics should be a live and direct view into the object
graph of both machine-readable code and human readable text so every
code is browsed within this larger context. This will reduce most of the
tedium of keeping code and doc in sync.

Regards .. Subbu




__------_-----------snip




In Seaside doc, I encabsulate a bit of knowkedge into Doclets .Doclets get their information from anywhere...class comment, Help page, Swiki page, (comments on topics like in stack exchange) and they live in image.


Collecting and storing them is easy,  Per Subbu's point, having them self organize is the key to creating the structures Tim listed in another thread.


The other very important principle is that they are displayable anywhere, and (ignoring security for now). Writable from any where.


I.e. an entry on the swiki becomes a docket in the system and is viewable in the Help Browser and visa versa.


Tl;dr....decouble the knowledge from the presentation, store it in image as its own system, ask it to organize it's doclets to organize themselves conceptually...i.e terse guide, book paragraph, design pattern...Subbu's and Tim's taxonomy.


Presentation and content creation become interface agnostic..Class comment, Help stuff, web based.




Cheers


Tty



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20200323/7af396f2/attachment.html>


More information about the Squeak-dev mailing list