=== Top of the Swiki === Attachments ===
Documentation within the Image
Note: Before making changes to this page, please read the guidelines to SqueakCentralProjects. Thanks.
Goal
While one might not think of this as a project, it has all the same surrounding issues of deciding how we want to do it, coordinating it amongst many contributors, and getting it right. The current project definition refers to getting the internal documentation (class and method comments) right, so that tutorials and other external documentation can leverage off it (and for the normal benefit of users and developers as well, natch).
Estimated completion date: December 32, 1999
Status
[August 8] project declared to exist
Implementors
Dwight Hughes
who else?
Implementors - please add your project and its status to Documentation Tasks In Progress and keep it updated.
Q/A, Integration
Ted Kaehler
Dwight Hughes
Richard Karpinski
General Commentary
[13 Aug, Ted Kaehler] I assume we are talking about writing better and more consistant content in class and method comments, and not some new mechanism for holding comments?
[13 Aug, Dwight Hughes] This is certainly a first and necessary baby step. My original interpretation of the Documentation project was that the documentation be outside of the image -- mainly because this is an easier path, though certainly much less satisfactory in the longer run. But this is even better. For myself, the ultimate goal I would like to see Squeak achieve is to equal and then exceed the integration and capabilities of the Symbolics Genera DocumentExaminer documentation system (http://kogs-www.informatik.uni-hamburg.de/~moeller/symbolics-info/docex/docex.html). They were actually not too far from a true literate programming system. Part of what made this work so well is the fact that most of it was based on a document database structure, not just flat texts. Mind you - there are a lot of steps between here and there.
[13 Aug, Ted Kaehler] For contrast, here is the state of DocPanes, my effort at external multimedia documentation. Any method or class may have a morphic pane (PasteUpMorph) associated with it. The panes live on the UIUC server. Anyone may edit a pane, but a person reviews their submission. I'd like there to be a mark in the method list beside any method that has a docPane on the server. All docPanes you have seen are cached on the local disk. Issues:
1) How can Squeak know what methods have docPanes, without going to the server often? New docPanes can be added at any time.
2) How can Squeak incrementally add to its local database of which methods have docPanes, without bringing a huge thing into memory? How can the additions be small files, but different users receive different amounts of the history of additions?
3) When you ask for a docPane, should it bring up a new window, or replace the docPane in a fixed window? A docPane might be big. When is it flushed from memory?
[19990813 Dave LeBlanc (whisper@accessone.com)] A couple of comments on this: Firstly, if you start putting all the docs into the image, won't that result in a fairly significant image bloat?. Secondly, requiring that Squeak be connected to the net to read docs isn't going to work if you're, for instance, in the woods communing with Squeak or in an airplane going to Asia. I'm also a little nervous about relying on the continued presence of a central doc server no matter who's running it.
[13 Aug, Dwight Hughes] Something I've considered is creating a new file to go along with the .changes and .sources files to be a documentation file for the image. The source mechanism that supports the .sources and .changes files can handle up to four external files.
[20 Aug 1999, Hannes Hirzel] Please add to "Documentation - tasks to do".
[25 Sep 1999, hh] See also Literate Squeaking
A list of items (most recent last) of the form
[date, author] comment
Anyone is invited to add to this list.
The implementors are free to remove and summarize any items more than two weeks old.