Hello to everyone who is interested in the documentation project. After a discussion on IRC, I have decided that I am being too quiet about the documentation project, and I would like to remedy that. Thus, this is the roadmap of what I have been working on and how you could help.
The Swiki, the primary source of documentation on Squeak, is severely disorganized. This is a political problem, I believe. There are also some technical problems, but they are not as severe:
- We could migrate the Swiki to a more modern system like Pier - We could move all the content to Sophie and have it accessible in the image as well as the web. - We could implement MagicBook[1] and be able to find out-of-date documentation
However, these technical issues are meaningless while political problems abound. So, here is a broad overview of what needs to be done to solve the political problem that Squeak documentation has no real maintainers:
1. Find all the existing documentation 2. Review it to assess it's quality 3. index it so we know what exists 4. for any projects without documentation, add them to the index, and contact the maintainer to try to get some documentation
These three steps will require a lot of work, but once finished, we will have a complete, but messy "first draft" of what the documentation for squeak should look like. This would be the time to discuss long-term technical ideas, like maintinance.
How can we index all existing documentation? we need a model of what such an index should look like, something which is a small but scalable subset of that index. I have been building a tutorial index, and I think it serves as a useful model to the larger documentation index we must eventually create: http://wiki.squeak.org/squeak/792
Thus, how can we get this project started?
First, I believe we should finish the tutorial index I have started. It is a smallish project, and it will help us bootstrap a political model for assembling larger projects. We need a political model if we are to ever tackle the huge projects that face the doc team.
Please reply with your thoughts, especially if you want to volunteer.
[1]: MagicBook: http://wiki.squeak.org/squeak/3004