One thing I didn't do, that I probably should have done, is to explicitly
list what I think our priorities should be regarding documentation. As much
as it pains me that we don't have a spell checker, for example, I'd put that
waaay behind a cleanup effort for class comments; I'd put *all* tool work
behind that.

I've thought a lot about how best to limit scope such that a documentation
project can deliver quickly. For a first shot, I'd like to limit scope to
what's in the image after one does 'Smalltalk unloadAllKnownPackages'. Of
course we should have great documentation for everything that comes in a
standard Squeak image, but knowing that our resources are limited, in a
triage I would call out everything in a core image as priority-1, with the
contents of a standard image as priority-2.

So here's my top three priorities (you may of course disagree:)

1. Get a process running around using HelpSystem.
2. A useful, current comment for every class.
3. Consider first method comments which show up in tools that can extract
them.

On Fri, Apr 30, 2010 at 2:24 AM, Ian Trudel <ian.trudel at gmail.com> wrote:

> Hello Casey,
>
> A short plan is the step in the right direction. I believe our
> community needs more sense of direction. I'd like to bring few things
> that seems to be missing in your proposal, for your consideration (and
> everyone else).
>
> There is no inclusion of additional tools in order to make sure we
> have quality documentation. For example, why not having hunspell [1]
> integrated? A good spell checker will make a huge difference. I would
> also consider versioning documentation important since our wiki
> suffers from the lack of it (shall we learn from our past mistakes?).
>
> [1] http://hunspell.sourceforge.net/
>
> I would much more consider contribute on documentation provided
> editing and formatting tools are available, ability to include
> screenshots, and other goodies. I don't care about the internal
> format. I am a big fan of LaTeX and I don't use it anymore because
> editing softwares nowadays do it much faster and it's way easier.
> Faster and easier mean more contributions.
>
> Your plan is overenthusiastic in my opinion. I don't think our
> community can undertake everything listed. It would be much better to
> look at what is the most needed in term of documentation and have
> people to focus on it. It will reduce the risks of failure. We can
> build around this documentation and slowly move on other parts. We
> need something usable for the largest segment of the community.
>
> Squeak Documentation Team is all right for a name. Let's stick to
> simple. Simple usually works better. :P
>
> Best regards,
> Ian.
> --
> http://mecenia.blogspot.com/
>
>


-- 
Casey Ransberger
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20100430/eb3e66aa/attachment.htm