Proposing class Category README or HOWTO for easy access to documentation within the system
Hi All,
Stefan Ducasse replied to me regarding my synapsis of the CMakeVMaker code.
Igor created all the logic of the CMakeGenerator but I guess that he did not add good class comments so I thought that it would be great if you can add the comment to a class so that it is not lost. Information external to classes is often lost.
And I agree with him.
In Linux/Open Source world, are the conventions of README and HOWTO. I propose that Squeak adopt two class categories for developers to add easy access to documentation on subsystems in the README category and quick howto_foo_a_bar classes in the HOWTO category.
I know we have the web, and there is a Help system, but I find the Help system a bit clunky to use and breaking from Squeak environment to Web for information breaks the flow.
A recent example of where this proposal would come in handy is the recent discussion about reviving Tweak for Squeak 4.5/4.6. The time investment to get up to speed is vastly increased by having to hunt for information.
just my .02
cheers.
tty
Interesting. Could you provide a small example for a class that you are familiar with of the README and HOWTO? Small so that it doesn't take too long, and an example so I can actually see what is being proposed. I think I like the idea, but...
-cbc
On Thu, Jun 12, 2014 at 11:29 AM, gettimothy gettimothy@zoho.com wrote:
Hi All,
Stefan Ducasse replied to me regarding my synapsis of the CMakeVMaker code.
Igor created all the logic of the CMakeGenerator but I guess that he did not add good class comments so I thought that it would be great if you can add the comment to a class so that it is not lost.* Information external to classes is often lost.*
And I agree with him.
In Linux/Open Source world, are the conventions of README and HOWTO. I propose that Squeak adopt two class categories for developers to add easy access to documentation on subsystems in the README category and quick howto_foo_a_bar classes in the HOWTO category.
I know we have the web, and there is a Help system, but I find the Help system a bit clunky to use and breaking from Squeak environment to Web for information breaks the flow.
A recent example of where this proposal would come in handy is the recent discussion about reviving Tweak for Squeak 4.5/4.6. The time investment to get up to speed is vastly increased by having to hunt for information.
just my .02
cheers.
tty
We already have a fairly decent Help system available; see the help item in the top docking bar menus. What we lack is content for that help system, and a clear organisation of it; consider the several workspaces, the Terse Guide, the Help Browser that also includes the terse guide. I’d suspect that having a nice link to available help info from the Browser might encourage more use of it.
The tool is decent and would be better with simpler organisation, but the real missing part is content. The problem is that writing good help & tutorial content is hard work. Take a look on the swiki to see how several groups and individuals have tried to build tutorials and lost steam after a while. I’ve been trying to clean up and update some of it but it takes a lot of thought and a startling amount of time.
On the plus side, a good bit of help/tutorial on a single, narrow area is still a good bit of help. It’s not you have to write a guide to the entire system in one go. Writing help info is a very good exercise when you are learning about a new bit of the system; nothing helps you organise your thoughts and test your understanding like trying to provide a clear explanation for others.
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Puts a finger in his ear so the draft through his head isn't annoying.
Hi Tim.
We already have a fairly decent Help system available; see the help item in the top docking bar menus. What we lack is content for that help system, and a clear organisation of it; consider the several workspaces, the Terse Guide, the Help Browser that also includes the terse guide. I’d suspect that having a nice link to available help info from the Browser might encourage more use of it.
I have used the Help System and I have practiced writing books in it. I must say I am not a fan of it for the reasons you give and some others I have forgotten. (ok, I opened the Help Browser and some reasons have come back to me: No search, no type-ahead to browse for topics, difficult to contribute to, etc).
What I have in mind is something like 'http://www.tldp.org/HOWTO/text/' for the HOWTO's but in Smalltalk category that "anybody" can write to to contribute and that is simple text.
Maybe the Help Browser is the way to go, but in my opinion, the learning curve and work required to contribute to it dissuade the community from using it.
cheers.
tty
On Jun 12, 2014, at 5:25 PM, tim Rowledge tim@rowledge.org wrote:
We already have a fairly decent Help system available; see the help item in the top docking bar menus. What we lack is content for that help system, and a clear organisation of it; consider the several workspaces, the Terse Guide, the Help Browser that also includes the terse guide. I’d suspect that having a nice link to available help info from the Browser might encourage more use of it.
The tool is decent and would be better with simpler organisation, but the real missing part is content. The problem is that writing good help & tutorial content is hard work. Take a look on the swiki to see how several groups and individuals have tried to build tutorials and lost steam after a while. I’ve been trying to clean up and update some of it but it takes a lot of thought and a startling amount of time.
On the plus side, a good bit of help/tutorial on a single, narrow area is still a good bit of help. It’s not you have to write a guide to the entire system in one go. Writing help info is a very good exercise when you are learning about a new bit of the system; nothing helps you organise your thoughts and test your understanding like trying to provide a clear explanation for others
Help system is a delivery system while wiki.squeak.org has lots of good content. A cool thing to do here is to have the Help system serve the wiki content. In the same way that SqueakMap uses a web interface for new content and then serves that content in the image with a GUI widget use Help system as a vector for the consumption of wiki pages.
I'm in the process of exploring how the XML pages used by Swiki as on-disk persistence can be converted into TinyWiki objects, into objects that can be stored in an SSRepository file and served by a hacked SS2. I have a workflow [1], but I need to make it work and then automate it.
I think that once I have the wiki pages saved as an SSRepository file, then anybody could download it, like a SqueakMap map file, and consume it with Help system.
Chris
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Puts a finger in his ear so the draft through his head isn't annoying.
[1]
NuSwikiPage name: 'Intro to 1.5' text: a String pulled from an XML file
1. Replace name spaces with hyphens (i.e. Intro-To-1.5 ) to be used later as the URI token like /squeaksource/Traits, /squeaksource/MineSqeeper, /squeaksource/Intro-To-1.5 2. Use the correct Swiki action to convert the page numbers (i.e. *1*) in the NuSwikiPage>>text into proper names for the links (i.e. *Intro to 1.5* ) 3. Make a dictionary where the keys are the name and the values the complete wiki format string. 4. Modify TWParser in TWWiki so that it creates HTML links instead of what it already does. 5. Feed the value, the wiki format string, into the TWParser and get a TWPage. 6. Push the keys and values into SSProject instances:
SSProject id: 'Intro-To-1.5' wiki: a TWPage
7. Put the SSProject into SSRepository 8. Serve with Ohana ( a hacked SS2)
The end result is that you modify SS2 ( with a project called Ohana) so that it serves Swiki pages as TWWiki pages. You've seen this before, because every single SS2 project has it's own wiki. That means a Swiki NuSwikiPage is converted to a TWWiki object, which is easily rendered with Seaside. And it opens to be edited just like any project wiki in SS2. Then move all 6100 Swiki pages to box4 as a single SSRepository file.
The point is that with all this conversion of godawful XML files into TinyWiki objects, I can create a separate conversion process and feed them to Help system. There's you're content. I like this idea. I've already done the worst parts. I'll explore it.
Hi Chris
I'm in the process of exploring how the XML pages used by Swiki as on-disk persistence can be converted into TinyWiki objects, into objects that can be stored in an SSRepository file and served by a hacked SS2. I have a workflow [1], but I need to make it work and then automate it.
I think that once I have the wiki pages saved as an SSRepository file, then anybody could download it, like a SqueakMap map file, and consume it with Help system.
Chris
That's a great idea.
Yea! :)
Chris
On Jun 12, 2014, at 6:43 PM, gettimothy gettimothy@zoho.com wrote:
Hi Chris
I'm in the process of exploring how the XML pages used by Swiki as on-disk persistence can be converted into TinyWiki objects, into objects that can be stored in an SSRepository file and served by a hacked SS2. I have a workflow [1], but I need to make it work and then automate it.
I think that once I have the wiki pages saved as an SSRepository file, then anybody could download it, like a SqueakMap map file, and consume it with Help system.
Chris
That's a great idea.
On Thu, Jun 12, 2014 at 02:25:37PM -0700, tim Rowledge wrote:
The problem is that writing good help & tutorial content is hard work. Take a look on the swiki to see how several groups and individuals have tried to build tutorials and lost steam after a while. I?ve been trying to clean up and update some of it but it takes a lot of thought and a startling amount of time.
I don't know if anyone has mentioned it recently, but the updates to the swiki are very good. I can now go to http://wiki.squeak.org/squeak and get an overview of Squeak, with links that quickly get me to useful content. Big improvement.
BTW, we need to fix the "Wiki" tab on the squeak.org page so that it takes you directly to wiki.squeak.org/squeak. Anyone know how to fix that?
Dave
I don't know if anyone has mentioned it recently, but the updates to the swiki are very good. I can now go to http://wiki.squeak.org/squeak and get an overview of Squeak, with links that quickly get me to useful content. Big improvement.
BTW, we need to fix the "Wiki" tab on the squeak.org page so that it takes you directly to wiki.squeak.org/squeak. Anyone know how to fix that?
Dave
Who can contribute to the wiki? eh. never mind. I had to scroll to find it, but here it is:
This site is an annex to the Squeak homepage at squeak.org in the form of a Wiki, which means that there is no designated editor. You can modify any page here (except the Help Guide), and add your questions, answers, and examples of Squeak code. If you see a way to improve the site, please feel free to do it yourself! If you are new to this site, please drop by the Acceptable Use page. Also, if you want to edit any page of this wiki, click the edit link in the upper menu of the page and when asked use squeak as username and viewpoints as password, as explained in the Squeak Documentation Team page. Don't know what a Wiki is? Try some of these great pages:
I will poke around.
thx, Dave.
On 12-06-2014, at 4:04 PM, David T. Lewis lewis@mail.msen.com wrote:
On Thu, Jun 12, 2014 at 02:25:37PM -0700, tim Rowledge wrote:
The problem is that writing good help & tutorial content is hard work. Take a look on the swiki to see how several groups and individuals have tried to build tutorials and lost steam after a while. I?ve been trying to clean up and update some of it but it takes a lot of thought and a startling amount of time.
I don't know if anyone has mentioned it recently, but the updates to the swiki are very good. I can now go to http://wiki.squeak.org/squeak and get an overview of Squeak, with links that quickly get me to useful content. Big improvement.
It’s a slow process - a lot of the changes to the front page I did over a year ago and some at the end of last year! I’ve tried to clean up the documentation & ‘squeak books’ pages, and made a start on pulling together some old and new tutorial stuff to try to make a coherent whole. It’s a huge project. More input needed.
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Calm down -- it's only ones and zeros.
On Thu, Jun 12, 2014 at 04:19:46PM -0700, tim Rowledge wrote:
On 12-06-2014, at 4:04 PM, David T. Lewis lewis@mail.msen.com wrote:
On Thu, Jun 12, 2014 at 02:25:37PM -0700, tim Rowledge wrote:
The problem is that writing good help & tutorial content is hard work. Take a look on the swiki to see how several groups and individuals have tried to build tutorials and lost steam after a while. I?ve been trying to clean up and update some of it but it takes a lot of thought and a startling amount of time.
I don't know if anyone has mentioned it recently, but the updates to the swiki are very good. I can now go to http://wiki.squeak.org/squeak and get an overview of Squeak, with links that quickly get me to useful content. Big improvement.
It?s a slow process - a lot of the changes to the front page I did over a year ago and some at the end of last year! I?ve tried to clean up the documentation & ?squeak books? pages, and made a start on pulling together some old and new tutorial stuff to try to make a coherent whole. It?s a huge project. More input needed.
I hope you are willing to accept a small amount of praise, glory, and gratitude in lieu of actual work.
I do think that it would be helpful to make this more directly visible from the squeak.org home page. The home page provides a nice welcome, but there is not much content behind it. It might be good if new users could quickly find their way to wiki.squeak.org.squeak.
Dave
On Jun 12, 2014, at 7:42 PM, David T. Lewis lewis@mail.msen.com wrote:
On Thu, Jun 12, 2014 at 04:19:46PM -0700, tim Rowledge wrote:
On 12-06-2014, at 4:04 PM, David T. Lewis lewis@mail.msen.com wrote:
On Thu, Jun 12, 2014 at 02:25:37PM -0700, tim Rowledge wrote:
The problem is that writing good help & tutorial content is hard work. Take a look on the swiki to see how several groups and individuals have tried to build tutorials and lost steam after a while. I?ve been trying to clean up and update some of it but it takes a lot of thought and a startling amount of time.
I don't know if anyone has mentioned it recently, but the updates to the swiki are very good. I can now go to http://wiki.squeak.org/squeak and get an overview of Squeak, with links that quickly get me to useful content. Big improvement.
It?s a slow process - a lot of the changes to the front page I did over a year ago and some at the end of last year! I?ve tried to clean up the documentation & ?squeak books? pages, and made a start on pulling together some old and new tutorial stuff to try to make a coherent whole. It?s a huge project. More input needed.
I hope you are willing to accept a small amount of praise, glory, and gratitude in lieu of actual work.
I do think that it would be helpful to make this more directly visible from the squeak.org home page.
I'll change that tomorrow.
Chris
The home page provides a nice welcome, but there is not much content behind it. It might be good if new users could quickly find their way to wiki.squeak.org.squeak.
Dave
On Thu, Jun 12, 2014 at 08:02:14PM -0400, Chris Cunnington wrote:
On Jun 12, 2014, at 7:42 PM, David T. Lewis lewis@mail.msen.com wrote:
On Thu, Jun 12, 2014 at 04:19:46PM -0700, tim Rowledge wrote:
On 12-06-2014, at 4:04 PM, David T. Lewis lewis@mail.msen.com wrote:
I don't know if anyone has mentioned it recently, but the updates to the swiki are very good. I can now go to http://wiki.squeak.org/squeak and get an overview of Squeak, with links that quickly get me to useful content. Big improvement.
It?s a slow process - a lot of the changes to the front page I did over a year ago and some at the end of last year! I?ve tried to clean up the documentation & ?squeak books? pages, and made a start on pulling together some old and new tutorial stuff to try to make a coherent whole. It?s a huge project. More input needed.
I hope you are willing to accept a small amount of praise, glory, and gratitude in lieu of actual work.
I do think that it would be helpful to make this more directly visible from the squeak.org home page.
I'll change that tomorrow.
Thanks Chris :)
Dave
squeak-dev@lists.squeakfoundation.org
-
Chris Cunningham -
Chris Cunnington -
David T. Lewis -
gettimothy -
tim Rowledge