This post originated from an RSS feed registered with Agile Buzz
by James Robertson.
Original Post: SmalltalkDoc
Feed Title: Cincom Smalltalk Blog - Smalltalk with Rants
Feed URL: http://www.cincomsmalltalk.com/rssBlog/rssBlogView.xml
Feed Description: James Robertson comments on Cincom Smalltalk, the Smalltalk development community, and IT trends and issues in general.
Mark Roberts and Rich Demers talk about SmalltalkDoc. Mark started with ST back in the late 70's at PARC. Rich started with VAST back in the 80's. What is SmalltalDoc?
Standards and Facilities to provide reference documentation for Smalltalk
Authoring tool in the IDE
Web Application for browsing
The goal is to separate the documentation from the implementation of the system - allow people to learn w/o reading all the code. The documentation can be gathered from a Store repository by the application. Who is the intended audience?
primarily new developers
reach out via the internet
not a substitute for PDF - an addition to online help
Why Smalltalk Doc?
Reduce the time/effort to learn ST - get them up to speed quickly
Provide a simple overview of the environment and lower the learning curve to a learning bump
Improve the "out of the box" experience for developers new to ST. Motivations:
Need reference doc - we used to have the "Cookbook" in 2.5, but it was huge, and never updated. The ObjectReference was a stab at doing this
Emphasis on use of the class library
"Learnability" vs. "Simplicity"
Learning the class and pkg library
Need to clarify the functionality of the system
One of the big issues is the API - what is it? In many cases, our libraries have no API in the sense that developers in other languages define the term. It's a manual "eyeball" process of inferring the API...
Making the system more approachable is a key goal
The general issue - we have a gap in knowledge - we doc the system, but do not have a "Users Guide" for new people. Using this:
Authoring content in the IDE
Generating content for the web
Browsing content for the web
Now Mark is going to demo the system. The system is built on a content mgmt system built atop an OODBMS. Presented via a VW web toolkit application. What he's got is a prototype that can produce a doc view of the class library - from the package and class view. Now on to Rich. Hmm. UML diagrams of the domain. I know these are useful, but w/o a camera, I can't convey what I'm looking at here....
They have a browser-like tool for displaying and editing content. Basically, the same information that was available on the web side is available in the browser view. The bottom view is an HTML Pane (Twoflower now - WithStyle eventually? Content entry is text. Interesting flare up of conversation on the concept of entering content - current prototype requires HTML tags - why not Wiki markup? Too much work - they want a WYSIWYG kind of tool in the end. The content will be stored as XML.
Q: How does this information get entered in the first place? A:: Information gathered automatically (garnered from the Smalltalk system), converted into an XML form, and then translated for display. The idea is to keep all this info with the code so that it gets versioned off in Store.
Q: Does this work at all with the Web Services work? A:: Huh?
Q: What about using something like the JavaDoc approach? A: The desire is to integrate this with the system. Should be possible to create a tool to "peel" the doc off from the system. The domain model is tied into the code, so it stays with it. The idea is to keep it that way.
Q: Will there be an interface for end users to "mark up" the documentation? A: The web side? Sure, that could be added via permissions. The tools themselves will be available for end customer use
Previous Topic
