I am considering doing a large overhaul on the documentation page on wwwtest.squeak.org. I started by fixing the broken links on the wwwtest site which had already been fixed on the main page.
I think that the Documentation page should link to the best documentation at the top, and only later point the user at the heap of out-of-date stuff. So I put links to Squeak by Example and my tutorial list at the top in nice-looking <h2> headers, and removed the Tutorials section, as my tutorial list is much better (imho). However, That is only two links on the rather large page, and they do not seem eye-catching at all. I am no web designer, so I am not sure how to fix this. Also, are there other docs we could put there that are not slightly embarrassing to show noobs?
Two things that are especially nice from my collection [1] are Maarten Maartensz's Squeak pages : http://www.maartensz.org/computing/squeak/squeak_index.htm and Stephane Ducasse's Smalltalk Exercises: http://stephane.ducasse.free.fr/Teaching/CoursAnnecy/0506-M1-OOP/OOPAvance.p...
Please help.
[1]: My collection of Squeak stuff; most are useful: http://wiki.squeak.org/squeak/5871
PS. I am not sure whether to cross-post this message to the doc-team list, so I did not. I am not sure if there is or should be a definable separation of duties between the two team's goals
Matthew Fulmer wrote:
I am considering doing a large overhaul on the documentation page on wwwtest.squeak.org. I started by fixing the broken links on the wwwtest site which had already been fixed on the main page.
The use of "Documentation" is a bit of a misnomer for this page. It really is a collection of useful ways to search and learn about squeak. Maybe we should think of another title instead of "documentation", as I do think something like this would be good on the main site (and point to the real documentation on the wiki.)
Maybe rename to "Resources"? Then provide useful ways to learn about squeak, including pointing to documentation.
PS. I am not sure whether to cross-post this message to the doc-team list, so I did not. I am not sure if there is or should be a definable separation of duties between the two team's goals
My take is that the documentation team is slated to provide ways for people to learn and edumacate themselves about squeak's environment, the smalltalk language, etc. I thought the team was going to create better documentation about the classes/methods and also provide links to all the wonderful documentation resources on the web (and at Amazon!)
I think it would also be nice if the documentation team helped developers, or build processes for them, so programmers find it easier (or force them to!) write documentation about their apps/code in the future (thus helping you from continually writing documentation!)
I think the webteam is responsible for maintaining the website that provides a frontend to everything about squeak. That includes ways to find the documentation, but also other important things that other groups are responsible for. For instance, the Foundation, where and how to download the latest squeak, providing some advertising and PR about squeak (e.g. the Features page.)
So, I see them different.
On Thu, Jun 07, 2007 at 06:24:51PM -0700, Brad Fuller wrote:
Matthew Fulmer wrote:
I am considering doing a large overhaul on the documentation page on wwwtest.squeak.org. I started by fixing the broken links on the wwwtest site which had already been fixed on the main page.
The use of "Documentation" is a bit of a misnomer for this page. It really is a collection of useful ways to search and learn about squeak. Maybe we should think of another title instead of "documentation", as I do think something like this would be good on the main site (and point to the real documentation on the wiki.)
Maybe rename to "Resources"? Then provide useful ways to learn about squeak, including pointing to documentation.
I don't really like the name Resources. "Resources" makes me think of things that make up a system and keep it going. Kind of generic. Either name would work, I guess.
Regarding specific parts of the page, Those Google search boxes look really weird to me, and I would never think to come use them. Would there be a way to put those as drop-down choices on some search box at the top of www.squeak.org? that is how several other sites do it. Or just put a search box up there that searches the website, the Swiki, SqueakPeople, the mailing lists, and (maybe) the IRC logs.
The doc team should probably move most of those links off the website and put them into a bigger, easier list on the Swiki, kind of like I did with the tutorial list.
PS. I am not sure whether to cross-post this message to the doc-team list, so I did not. I am not sure if there is or should be a definable separation of duties between the two team's goals
My take is that the documentation team is slated to provide ways for people to learn and edumacate themselves about squeak's environment, the smalltalk language, etc. I thought the team was going to create better documentation about the classes/methods and also provide links to all the wonderful documentation resources on the web (and at Amazon!)
Definitely!
I think it would also be nice if the documentation team helped developers, or build processes for them, so programmers find it easier (or force them to!) write documentation about their apps/code in the future (thus helping you from continually writing documentation!)
This is what I am currently focusing on. It will take some time, though, since I have not done much squeak hacking yet.
I think the webteam is responsible for maintaining the website that provides a frontend to everything about squeak. That includes ways to find the documentation, but also other important things that other groups are responsible for. For instance, the Foundation, where and how to download the latest squeak, providing some advertising and PR about squeak (e.g. the Features page.)
So, I see them different.
Thanks a lot. This answers some of the questions I asked in my next email too.
Matthew Fulmer wrote:
On Thu, Jun 07, 2007 at 06:24:51PM -0700, Brad Fuller wrote:
Matthew Fulmer wrote:
I am considering doing a large overhaul on the documentation page on wwwtest.squeak.org. I started by fixing the broken links on the wwwtest site which had already been fixed on the main page.
The use of "Documentation" is a bit of a misnomer for this page. It really is a collection of useful ways to search and learn about squeak. Maybe we should think of another title instead of "documentation", as I do think something like this would be good on the main site (and point to the real documentation on the wiki.)
Maybe rename to "Resources"? Then provide useful ways to learn about squeak, including pointing to documentation.
I don't really like the name Resources. "Resources" makes me think of things that make up a system and keep it going. Kind of generic. Either name would work, I guess.
I think "Resources" is better than "Documentation".
== re·source (rē*'*sôrs', -sōrs', -zôrs', -zōrs', rĭ-sôrs*'*, -sōrs*'*, -zôrs*'*, -zōrs*'*) pronunciation /n./
1. Something that can be used for support or help: /The local library is a valuable resource./ 2. An available supply that can be drawn on when needed. Often used in the plural. 3. The ability to deal with a difficult or troublesome situation effectively; initiative: /a person of resource./ 4. Means that can be used to cope with a difficult situation. Often used in the plural: /needed all my intellectual resources for the exam./ 5. 1. resources The total means available for economic and political development, such as mineral wealth, labor force, and armaments. 2. resources The total means available to a company for increasing production or profit, including plant, labor, and raw material; assets. 3. Such means considered individually.
===
Maybe someone could come up with a better name.
Regarding specific parts of the page, Those Google search boxes look really weird to me, and I would never think to come use them. Would there be a way to put those as drop-down choices on some search box at the top of www.squeak.org?
I don't know. There already is a "search" link on the top right of the page.
that is how several other sites do it. Or just put a search box up there that searches the website, the Swiki, SqueakPeople, the mailing lists, and (maybe) the IRC logs.
The doc team should probably move most of those links off the website and put them into a bigger, easier list on the Swiki, kind of like I did with the tutorial list.
Good idea. I bet the google search is better than the swiki search, though. That one is not too good. If so, it'd be nice to repoint the wiki search to a page where one could search using google. Maybe having a list of boxes.
There is also this: http://google.com/coop/cse?cx=008315932112852043911%3Ayuibfrpnbc0
On Thu, Jun 07, 2007 at 07:06:28PM -0700, Brad Fuller wrote:
I think "Resources" is better than "Documentation".
Me too.
Regarding specific parts of the page, Those Google search boxes look really weird to me, and I would never think to come use them. Would there be a way to put those as drop-down choices on some search box at the top of www.squeak.org?
I don't know. There already is a "search" link on the top right of the page.
Ah. there is. I never even saw it. it is tiny.
that is how several other sites do it. Or just put a search box up there that searches the website, the Swiki, SqueakPeople, the mailing lists, and (maybe) the IRC logs.
The doc team should probably move most of those links off the website and put them into a bigger, easier list on the Swiki, kind of like I did with the tutorial list.
Good idea. I bet the google search is better than the swiki search, though. That one is not too good. If so, it'd be nice to repoint the wiki search to a page where one could search using google. Maybe having a list of boxes.
Not sure what you mean by "a list of boxes", or what each box might do or be.
There is also this: http://google.com/coop/cse?cx=008315932112852043911%3Ayuibfrpnbc0
Never saw that. looks quite useful.
I looked at the documentation page on the test server and it starting to look good. Craig Latta is also writing a book about Spoon but it will contain a lot of Squeak and Smalltalk as well, if it gets finished ;-) (http://www.netjam.org/projects/spoon/)
Karl
On Thu, 2007-06-07 at 19:06 -0700, Brad Fuller wrote:
I think "Resources" is better than "Documentation".
I would just like to point out that the absolute number one request from anyone new to this community or even that has been around on the fringes for a while is for Documentation. I think it is absolutely essential that while this need not be exactly the front page of Squeak.org it must be a visible and quickly found link. I'll note that I have not looked at the page under discussion here. I simply want to point out that on Squeak.org there should be a page on how to find Documentation and Learning materials and it should be easily found. Also I believe that the standard is for this page to be called Documentation. This is a standard for any website whose focus is on a software development product, particularly open source ones.
Ken
Ken Causey wrote:
On Thu, 2007-06-07 at 19:06 -0700, Brad Fuller wrote:
I think "Resources" is better than "Documentation".
I would just like to point out that the absolute number one request from anyone new to this community or even that has been around on the fringes for a while is for Documentation. I think it is absolutely essential that while this need not be exactly the front page of Squeak.org it must be a visible and quickly found link. I'll note that I have not looked at the page under discussion here. I simply want to point out that on Squeak.org there should be a page on how to find Documentation and Learning materials and it should be easily found. Also I believe that the standard is for this page to be called Documentation. This is a standard for any website whose focus is on a software development product, particularly open source ones.
I don't know if it is the absolute number one request, I haven't been keeping count, though ;-)
I see your point. Makes sense.
On Thu, Jun 07, 2007 at 06:50:54PM -0700, Matthew Fulmer wrote:
Regarding specific parts of the page, Those Google search boxes look really weird to me, and I would never think to come use them. Would there be a way to put those as drop-down choices on some search box at the top of www.squeak.org? that is how several other sites do it. Or just put a search box up there that searches the website, the Swiki, SqueakPeople, the mailing lists, and (maybe) the IRC logs.
A few more changes: - I removed those search boxes from the documentation page. - I also re-organized the top few sections, merging the video, book, and tutorial list into a "Useful Resources" heading. - Added the "Discovering Better Code Series" as a top-document, as it was particularly useful today, as someone was looking for a document on exactly that topic - Moved the link to http://squeak.joyful.com/Sites to the "Community" page - Replaced links to irc and the mailing list with a single link to the Community page
Still to be done: - figure out what to do with the links at the bottom of the page. Especially the link to squeaknews.com. I am examining that site to see what is there; unfortunately, my system is not able to mount their zipped ISO images right now, due to some error with my /dev/loop device. - Move the section "Exploring the code" onto a dedicated wiki page. I am sure an appropriate page exists, but I need to go to bed.
My goal for this page is to be able to point to it as "the" place to direct anyone unfamiliar with squeak able to operate the system. More specifically, I am about to start a Seaside tutorial, and I want to be able to assume that the reader is already familiar with Squeak. I would like to justify that assumption with only one link: http://www.squeak.org/Documentation
How well does the page meet that criteria? Is it a valid criteria? If so, should the page be renamed "Getting Started" ?
The doc team should probably move most of those links off the website and put them into a bigger, easier list on the Swiki, kind of like I did with the tutorial list.
Still todo.
On Sun June 24 2007 9:59 am, Brad Fuller wrote:
On Sun June 24 2007 12:38 am, Matthew Fulmer wrote:
Still to be done:
- figure out what to do with the links at the bottom of the page. Especially the link to squeaknews.com.
the squeaknews link can be removed. We already have a feed and links on the right side of every page.
oppss.. ken pointed out that squeaknews.com is not news.squeak.org
please ignore my msg
Matthew Fulmer wrote:
On Thu, Jun 07, 2007 at 06:50:54PM -0700, Matthew Fulmer wrote:
Regarding specific parts of the page, Those Google search boxes look really weird to me, and I would never think to come use them. Would there be a way to put those as drop-down choices on some search box at the top of www.squeak.org? that is how several other sites do it. Or just put a search box up there that searches the website, the Swiki, SqueakPeople, the mailing lists, and (maybe) the IRC logs.
A few more changes:
- I removed those search boxes from the documentation page.
- I also re-organized the top few sections, merging the video, book, and tutorial list into a "Useful Resources" heading.
- Added the "Discovering Better Code Series" as a top-document, as it was particularly useful today, as someone was looking for a document on exactly that topic
- Moved the link to http://squeak.joyful.com/Sites to the "Community" page
- Replaced links to irc and the mailing list with a single link to the Community page
This page looks good.
Still to be done:
- figure out what to do with the links at the bottom of the page. Especially the link to squeaknews.com. I am examining that site to see what is there; unfortunately, my system is not able to mount their zipped ISO images right now, due to some error with my /dev/loop device.
As the stuff on the Squeaknews site starts to get old I think the link can be moved over to the swiki
- Move the section "Exploring the code" onto a dedicated wiki page. I am sure an appropriate page exists, but I need to go to bed.
My goal for this page is to be able to point to it as "the" place to direct anyone unfamiliar with squeak able to operate the system. More specifically, I am about to start a Seaside tutorial, and I want to be able to assume that the reader is already familiar with Squeak. I would like to justify that assumption with only one link: http://www.squeak.org/Documentation
How well does the page meet that criteria? Is it a valid criteria? If so, should the page be renamed "Getting Started" ?
I think documentation is better.
The doc team should probably move most of those links off the website and put them into a bigger, easier list on the Swiki, kind of like I did with the tutorial list.
Still todo.
Karl
On Sun, Jun 24, 2007 at 12:38:21AM -0700, Matthew Fulmer wrote:
On Thu, Jun 07, 2007 at 06:50:54PM -0700, Matthew Fulmer wrote:
Regarding specific parts of the page, Those Google search boxes look really weird to me, and I would never think to come use them. Would there be a way to put those as drop-down choices on some search box at the top of www.squeak.org? that is how several other sites do it. Or just put a search box up there that searches the website, the Swiki, SqueakPeople, the mailing lists, and (maybe) the IRC logs.
One more change: I put Stephan Wessel's excellent tutorial at the very top of the page.
Still to be done:
- figure out what to do with the links at the bottom of the page. Especially the link to squeaknews.com. I am examining that site to see what is there; unfortunately, my system is not able to mount their zipped ISO images right now, due to some error with my /dev/loop device.
- Move the section "Exploring the code" onto a dedicated wiki page. I am sure an appropriate page exists, but I need to go to bed.
I punted on this issue. I deleted the rest of the page and put it at http://wiki.squeak.org/493 . Except for the books and papers, there was nothing particularly interesting on the rest of the page. I will try to make a good book list, similar to my tutorial list, soon.
My goal for this page is to be able to point to it as "the" place to direct anyone unfamiliar with squeak able to operate the system. More specifically, I am about to start a Seaside tutorial, and I want to be able to assume that the reader is already familiar with Squeak. I would like to justify that assumption with only one link: http://www.squeak.org/Documentation
Thanks to Stephan's new tutorial and Squeak by Example, I would say this goal has been met. I moved the contents of the test site to the main site
From: Matthew Fulmer tapplek@gmail.com To: webteam@lists.squeakfoundation.org,Squeak documentation team squeak-doc@lists.squeakfoundation.org Subject: Re: [Webteam] Documentation page update Date: Tue, 3 Jul 2007 18:35:18 -0700
On Sun, Jun 24, 2007 at 12:38:21AM -0700, Matthew Fulmer wrote:
On Thu, Jun 07, 2007 at 06:50:54PM -0700, Matthew Fulmer wrote:
I punted on this issue. I deleted the rest of the page and put it at http://wiki.squeak.org/493 . Except for the books and papers, there was nothing particularly interesting on the rest of the page. I will try to make a good book list, similar to my tutorial list, soon.
Was there a typo in the link? I clicked on that link but I got a 404 error : The requested URL (http://127.0.0.1:8080/493) was not found on this server.
Larry Trutter
_________________________________________________________________ http://newlivehotmail.com
On Thu, Jul 05, 2007 at 06:39:00AM -0500, Larry Trutter wrote:
From: Matthew Fulmer tapplek@gmail.com To: webteam@lists.squeakfoundation.org,Squeak documentation team squeak-doc@lists.squeakfoundation.org Subject: Re: [Webteam] Documentation page update Date: Tue, 3 Jul 2007 18:35:18 -0700
On Sun, Jun 24, 2007 at 12:38:21AM -0700, Matthew Fulmer wrote:
On Thu, Jun 07, 2007 at 06:50:54PM -0700, Matthew Fulmer wrote:
I punted on this issue. I deleted the rest of the page and put it at http://wiki.squeak.org/493 . Except for the books and papers, there was nothing particularly interesting on the rest of the page. I will try to make a good book list, similar to my tutorial list, soon.
Was there a typo in the link? I clicked on that link but I got a 404 error : The requested URL (http://127.0.0.1:8080/493) was not found on this server.
yes; it should be http://wiki.squeak.org/squeak/493
webteam@lists.squeakfoundation.org
-
Brad Fuller -
karl -
Karl
-
Ken Causey -
Larry Trutter -
Matthew Fulmer -
Matthew Fulmer