Documentation - tasks to do (Historical)
Last updated at 7:16 am UTC on 5 April 2007
Here is a list of volunteers to the documentation project:
Add your name and email to volunteer
- Brent Vukmer bvukmer@blackboard.com
- Hannes Hirzel hannes.hirzel.squeaklist _at_ bluewin.ch
- Lic. Edgar J. De Cleene edgardec2001@yahoo.com.ar
- Doug Clapp dclapp@qwest.net
- Chris Burkert - chbu - chris@chrisburkert.de
- Torsten Bergmann TBn@phaidros.com
- Giovanni Giorgi jj@objectsroot.com
- Dan Ingalls Dan@SqueakLand.org
- Richard Staehli rstaehli@acm.org
- Jeffrey Edgington jedgingt@du.edu
- John Voiklis voiklis@redfigure.org
- John Pfersich jp1660 at att dot net
- Tom Koenig tomkoenig@mindspring.com
- Jack Keel jhkeel@wiscDOTedu
- Matthew Fulmer tapplek@gmail.com
How to help us document Squeak
Note to Volunteers: At the bottom of this page are signatures. hjh does this cool thing where he has a signature and a personal page. He can sign pages with just hjh and you can follow the link to his personal page. Try it! You might want to do the same.
The page Documentation Team Diary (Historical) reflects the current activity of the team.
Deliverables
- SUnit tests
- This verifies what is documented as well as providing documentation.
- Class comments within Squeak (with hypertext links)
- Updated Swiki pages
- Some of them may be just harvested moved and moved to an SUnit test or a class comment, then deleted and a note with a pointer)
- HOW-TOs
- here on the swiki
- on other web sites
- as a Smalltalk comment in the form of a change set
- "Magic Book Idea (2003)" - documentation within Squeak which uses its multi-media capabilities to illustrate the use and power of Squeak for both developers and naive users. Details see Magic Book Idea (2003).
- 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
The points are not numbered; this implies that the order is not important - we take anything what is done.
Areas of documentation
Procedures
- Use the Wiki conventions. (Please post your additional suggestions there).
- Don't Bloat The Image - new documentation and tools should not add yet more bloat to the image.
- Code comments are fine, they don't add bloat.
- Other new tools and documentation need to be very small, or optional to the standard contents of the image.
- For na???ve users we may want something like a "Take the Tour" button, which loads the magic book. There is already a "tour" which could be updated.
- Clean Up the Swiki - review the swiki and update or clean up its documentation. This includes:
- Add recipes to the Squeak Cookbook or probably better move the content from there to the FAQ
- Open an index page, a glossary page, a comprehensive toc page: you find a start of this under Squeak Documentation Project
- Develop a set of paths or "guided tours" within Squeak. Use the hyperlink feature in the Squeak class documentation. Point of depart is probably the Object class. A tour could go to the collection classes; a second to the basic GUI classes; a third to the Morphic classes; a fourth to the Swiki classes ....
- Check Documentation Team Diary (Historical) and update it accordingly
- Make references to SqueakMap where needed.
- Solicit volunteers. Solicit volunteers. Solicit volunteers. :)
Important internal links specific to documentation