Documentation Tools Project
Last updated at 12:22 am UTC on 8 April 2007
The goal of this project is to make better tools for documenting Squeak.
First, a Warning
This project is the least critical of the doc team's projects, but it is probably the most fun. There is a slight, dark tendency within the Squeak community to make tools and then never use them. This tendency is partially responsible for giving some people the idea that Smalltalkers are elitists with no real-world worries. Documentation work is noble, and the right tools can make it easier. However, we must not fall into the trap of doing only the fun part of the task (building tools), and not the important part (writing helpful documentation). As Ron points out, it is all too easy to do
There are two tools used to manage a lot of Squeak Documentation:
- Class and Method Comments support Hypertext
- This Swiki
Web interface to Squeak's comments
After a discussion on IRC with Ken Causey, I decided it is a really good idea to make a web-interface to Squeak's comments. Stephane Ducasse affirmed this in an email sent soon after.
Other Ideas
If you have a good idea for a documentation tool, put it here. The Squeak Documentation Team may pick it up at a later date.
- Magic Book Idea (2003) (an email on the Magic Book)
- Message Dictionary
- Sources of Inspiration
- Folklore
- Shared Recipes
- A "Take the Tour" button in the image, which loads the magic book. There is already a "tour" which could be updated.
- Code Comment "Scooper" - a tool which sweeps all the code comments into a format which allows them to be scanned and crossed reference (hyperlinked) easily (more easily than using the existing browsers). The idea here being to provide a different cognitive "view" on the code, not to add yet another browser. So it needs to be powerful enough to justify its existence. An similar thing could be a documentation browser or some Star Browser entries.
- An ExampleBrowser
