Mark Roberts and Rich Demers. Mark has been in Smalltalk off and on since the 70's.

What is it? It is a new Cincom project for standards and facilities to provide reference documentation for Smalltalk. Authoring tool in IDE. Web Application for browsing.

There are things we can currently comment, such as methods and classes, but there are parts of the system that we cannot document at the moment, such as categories.

SmalltalkDoc is a way to produce this documentation and a web application to publish this information on the internet. The documentation can be generated automatically. You can add more documentation and the publishing of it will happen automagically.

There is implementation stuff and there is public stuff that people can expect to be able to code. There's nothing semantic inside the system when you say public - it's not enforced like in other languages. It is soft for developers - "a candidate for re-use"

The web application looks at a store database to build the content on the web!

Intended Audience: Primarily new developers, reach out to them via the internet. Not a substitute for PDF documentation or on-line help.

Why SmalltalkDoc? Reduce time/effort required to evaluate, and learn Smalltalk. Provide simple overview of the Smalltalk Environment, its functionality. Improve new-user experience by increasing transparency.

Smalltalkers talk about developer productivity, but this is for seasoned developers. New developers don't experience this because they have a steep learning curve.

Concrete motivations: A need for reference documentation. New version of "Object Reference". Emphasis on the use of class library.

There was once a book called the Object Reference that shipped with VisualWorks. It gave detailed documentation on all the public classes and methods. But this no longer occurs (for ten years). With SmalltalkDoc that will come back.

Learnability vs Simplicity. Learning class and package library, need to clarify the functionality. Learning and growth. But the simplicity of Smalltalk makes learning it hard when there is no simple way to start and get in to it.

Nearly half of the classes in the base system don't have classes and the ones that do are often out of date.

Using SmalltalkDoc: Authoring the content in the IDE. Generating content for the web. Browsing the content for web.

The web application has 'Home', 'Overview', 'Bundles', 'Packages', 'Glossary' and 'Search'. There's also an option to register as a user and login. The overview is showing packages and bundles with a hierarchy of information by areas. The look and feel is very simple and to the point and well designed.

The system uses XML internally.The framework has many 'outs'. It stores in Omnibase, outputs to web applications but also has an import/export in an XML format as well.

The SmalltalkDoc domain model basically mirrors the normal Smalltalk domain. For example, a Namespace maps to NamespaceDoc. Package maps to PackageDoc, etc. There are some objects that are just strings. In SmalltalkDoc they can also be documented, such as events and protocols.

They've also made a browser inside Smalltalk that browses SmalltalkDoc information to help them develop things. They'll integrate in to RB once they have it working right. To integrate straight away would get in their way.

The tabs show all the documentation information. Such as version, author, name, last modified, stored XML, exported XML, documentation and an editor version of the page.

The documentation tab is using TwoFlower. They want inline editing and they're hoping to use WithStyle eventually for that. So currently they have a "..." link that takes you to a separate page for editing a field.

They're not making developers repeat what's already in the domain model, it sucks that in from the real object. SmalltalkDoc is more about the annotations of that information.

Some of the documentation has formatting in it, because they want a very rich formatting environment. Links to things, figures (especially figures), tables, bold, underline, etc. To do this at the moment they insert XHTML tags inside the text editor window. In WithStyle this wouldn't be a problem, since you tend not to see the XML in WithStyle.

Joke from Sam: It'll be called Pollock.

Question: Why not use the Wiki formatting tags?
Rich: It's a very poor tag formatting. It doesn't show you what you get.

The stored XML version is quite brief. But the Exported XML version is massive. It contains absolutely everything that you would need to recreate the SmalltalkDoc system in another database.

The big work is about what information to capture, not so much on the interface they have so far.

Question: How is this informatio entered in the first place and where is it kept?
The information is converted in to XML, entered through the UI. All of this will be kept in store with version control.

Question: How does this map to what Tamara is doing with WebServices?
Not sure, talk offline.

Question: JavaDoc is useful becuase you don't have a method level scope. Are you going to change the existing browsers to have a 'flat' view? Can it be shown side by side?
Basically, we've just added a Documentation tab to the tool. It should be possible to 'peel off' the Documentation tab in to a parallel window.

The documentation is related to the code, there's a tight link between them in this system. To populate most of this the RB can already guess the types of arguments, etc.

Question: How do you promote something from private to public?
There will need to be some way to identify those, but that isn't done yet.

Question: How does the SmalltalkDoc XML relate to the VW fileout XML?
The documentation strings end up as part of the file out.

Question: stic.org is used in the namespace. Does that mean anything?
We're hoping.

Question: In UI, there is a UI definition. Is there going to be a documentation interface for the UI? To provide end-user documentation?
At the moment, it's a content management system. Answered wrong question. Answer is yes for use in customer applications.

Question: What is the time frame from here to product?
There will be a prototype in the next release (7.3) and the remaining functionality will be rolled out over the next year.