[Webteam] Documentation page update

[Matthew Fulmer]

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 -- http://mtfulmer.wordpress.com/
Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808