This post originated from an RSS feed registered with Agile Buzz
by James Robertson.
Original Post: Trying the SmalltalkDoc preview
Feed Title: Richard Demers Blog
Feed URL: http://www.cincomsmalltalk.com/rssBlog/rademers-rss.xml
Feed Description: Richard Demers on Smalltalk
VW7.3 ships with SmalltalkDoc as a preview. It is incomplete and not yet intended to be used for serious documentation work, but Mark Roberts and I are hoping people will be willing to review it and comment. The preview includes a plugin to the RB that you can play with, and an Overview document that describes the project in some detail.
All you have to do is load the SmalltalkDoc parcel and open a new Refactoring Browser. When you select something in the browser, you'll see a Documentation tab in the RB's tool area. The documentation for the selected item then appears in the RB's tool pane -- not that there is any real documentation at this point, but you can enter/edit some if you want.
Documentation is presented in a HTML widget, with links to specialized editors for each documentation element (summary, keywords, description, etc.). For example, click on the Summary link and the Summary Editor appears, where you can enter whatever summary text you want. Click the editor's Apply button and your text appears in the RB's documentation tool.
I've tried to make the process of entering/editing documentation as convenient as possible. For example, once you have opened an element editor, it stays open and "follows" whatever element links you select in the documentation tool or objects you select in the RB's navigator pane. Further, the element editor has Next and Previous buttons to make it easy to enter multiple elements for a single object.
As I mentioned, the editors for each element are specialized. Some elements need simple text, others need HTML tagged text, and some need lists of various types, so I provided Help for each. If you leave it open, the Help window "follows" whatever is selected in the element editor and in the RB navigator.
SmalltalkDoc (sparsely) retains whatever elements you enter in the Store, along with the object being documented (actually a bit more complex than this!), but again, I must warn you not to begin using SmalltalkDoc for serious work. There are no guarantees that it will work exactly the same in future releases.
If you read the Overview document shipped with the SmalltalkDoc preview, you'll see there is a lot more planned for SmalltalkDoc than just this tool -- but it doesn't exist yet. We hope to make the editing of documentation a lot easier, and to automatically include a lot of existing information from the Smalltalk image and Store. Ultimately, there will also be a facility for snapshotting an existing set of documentation and making it available via a web server. But that's all for the future...
At this point, the SmalltalkDoc team (Mark and me) needs feedback:
Are we documenting the right parts of Smalltalk (bundles, packages, classes, events, methods, etc) with the right set of elements? Too much detail? Too little?
How would you use SmalltalkDoc for your projects? For every object? For key API's? For architectural/design information? For what?
How important is the inclusion of figures and diagrams (via jpegs) in your documentation?
How would you go about entering and maintaining documentation based on the development process you use: ad-hoc, waterfall, XP, etc.?
What other documentation-related tools would you like to see included in SmalltalkDoc?
Or do you think the whole think is misconceived and a big waste of time? If so, why?
Again, it is important that we get some feedback so that SmalltalkDoc meets real needs and so that the Cincom VisualWorks team hears that integrated documentation is really needed.
Previous Topic
