Macrobyte Resources Conversant Developer Central
Internet groupware development platform
First Look at the Documentation Outline




 

Topic: First Look at the Documentation Outline

Shown in forward chronological order.
Reverse chronological order | Hierarchical outline view

Messages: 14 of 14.
Pages: 1
First Look at the Documentation Outline (#299)
Posted: 6/5/2002; 4:33 PM by Seth Dillingham
Modified: 6/5/2002; 7:03 PM by Seth Dillingham
Response to: Top of Thread.
Edit | Reply
The basic outline of the documenation that we're writing for Conversant is ready, and we'd like to hear your comments on it. You probably won't learn much from reading the outline (it's really just a table of contents), but your feedback will help us finalize it.

The 1.0 release of Conversant is waiting for just two things: documentation and a licensing tool. The licensing tool is almost ready, but the docs are not. We're not planning to write all of these docs before the release, as that'll take too long, but we are going to finish the most important parts. That's another part you can help with: which parts are the most important to you?

As you peruse the outline, you'll see that there are question marks in some places. These are the things we're not sure about yet, and are definitely subject to change. (None of it is set in stone, but those areas with question marks are the least stable.)

Finally, you can read the outline either on the web site, or in the attached outline file (if you have Radio or Frontier installed).

Enough preamble! Your comments are welcome and most appreciated...


Outline of Documentation for Conversant
Preface
Introduction
Overview of Conversant
Philosophy
Features and Benefits
Developers: Frameworks vs. Applications
Conversant comes with both
Example Uses?
Concepts and Terminology
Zones
Conversations
Members
Groups
Messages
Enclosures
Preferences
Templates
Pages (Files and Folders)
Getting Started
Installing Covnersant
Creating a Conversant Site
From the wizard
From scratch
Administrators
Adding Members
Messages
Creating
Editing
Deleting
Bound Message Pages
Macros (Intro)
Conditional Macros (Intro)
Templates (Intro)
Admin Interface
Overview
Members
Overview
Creating, Editing, and Deleting Members
Setting Member Prefs
Groups
Overview
Creating, Editing, and Deleting Members
Setting Member Prefs
Conversations
(All items in this section should discuss only the functionality offered by the page in the admin interface, and then refer to other pages for more information on the related feature in Conversant.)
Overview
Messages
Preferences
Labels
Custom Fields
IP Security
Javascript
Logs
Navigation
Page Themes
Resources
Structure
Stylesheets
Templates
Zone
Overview
Preferences
IP Security
System
Overivew
Zones
Preferences
Administrators
Logs
Macros
Overview
Format
Parameters
Evaluation
Examples
Conditional Macros ?
(too advanced for this section?)
Templates
Overview
Read-Only
Types
Creating
Editing
Deleting
Pre-Compiled ?
InsertTemplateMacro ?
Javascript
Overview
Editing
Javascript macro
Linking vs. Embedding
Stylesheets (CSS)
Overview
Editing
Stylesheet macro
Linking vs. Embedding
Resources
Overview
Types
Custom Fields
Overview
Types
Conditional Macros
Overview
Format
Complex Conditionals (Parens and boolean operators)
Page Types
Overview
Advanced Query Page
Bound Message
DG Calendar Page
Directory Mirror
Enclosure Page
Full Thread
Query ?
Redirect Page
Topics Page
Weblog
Weblog View
WebOutline
Security
Overview
Web
Email
Guests, Members, and Administrators
Plugins
Overview of Conversant Plugins
Everything's a Plugin (Philosophy of the Plugin Interface)
Default (Shipping) Plugins
Example Uses for Custom Plugins ?
Create Your First Plugin
(this plugin will be used for all subsequent sections of the plugings docs, and if the read the docs from beginning to end they'll have a new, fully-functional plugin that makes use of all of the major features)
Instructions for starting a new plugin
Format of New Plugins (what goes where)
Only include what the plugin needs (optional parts)
Callbacks
Overview
How they're called
Review of what's available
Add some callbacks to your plugin
Read-Only Templates
Overview
Review: Template Types and Pre-Compiled Templates
Add some read-only templates to your plugin
Preferences
Overview
Add some preferences to your plugin
Macros
Overview
Parameters
No-further-processing
Post-processing options
(urlEncode, entify, etc.)
Add some templates to your plugin
Add the Conv_processMacros callback
Pages
Overview
#content receiver script
#objectNotFoundHandler receiver script
#processVirtualPage receiver script
Supporting callbacks in your pages
Page Properties
Direct callbacks from MRI's pages scripts
Create a new page type in your plugin
Custom Field Types
Overview
?
Conditional Macros
Overview
?
Interfaces
Overview
?
Styles ?
Overview
?
Tools
Overview: "Put anything in the tools table."
Membership Mgmt. and Databases
Overview
Groups
Conversant.members vs. Twine.users
Default user engines
Writing a custom user engine
Message Databases
Overview
Conversant.messages vs. Twine.messagestore
Default Messagestore engines
Writing a custom messagestore engine
Appendix - Conversant API Reference
Overview
Conversations
IO
Members
Messages
Plugins
Preferences
Scheduler
Styles
System
Templates
Zones
Appendix - Callback Refnerence
Overview
(Should this be part of the API reference, as it will have a similar structure? There are also callbacks in the IO plugins which might make that awkward, so I'm voting for a separate callback reference.)
Appendix - Conditional Macro Reference
Overview
Appendix - RSS and other XML Formts
Overview
RE: First Look at the Documentation Outline (#300)
Posted: 6/6/2002; 1:29 AM by Donald W. Larson
Modified: 6/6/2002; 1:29 AM by Donald W. Larson
Response to: 299
Edit | Reply
My only suggestion would be to add example code for each place that needs it from a beginner's point of view. Many texts on the Internet omit that very important aspect of using proper syntax.

I know that request is a pain to implement, but i think it is a worthwhile effort at some level anyway.

Keep up the great work!

Don

RE: First Look at the Documentation Outline (#301)
Posted: 6/6/2002; 11:15 AM by Samuel Reynolds
Modified: 6/6/2002; 11:15 AM by Samuel Reynolds
Response to: 299
Edit | Reply
Just a few things:

1. Licensing tool: Will this be available to/licensable by third-party developers? I've been puzzling about how to enforce plugin licenses (for Manila plugins at the moment, but for Conversant plugins when I get that far along).

2. My highest priority: documentation on Plugins. Required and optional elements, install/un-install process, etc.

3. Templates: Please include a note/reference in the templates intro clarifying where *all* templates may be found. One of the worst problems I had when starting with Conversant was *finding* the dratted things. *Some* are in the Templates section of the admin page (where I assumed I would find all templates, but where only a few actually appear--notably the page, weblog, and bound-page templates). Others are scattered through other sections of the admin page.

4. Typos:

  • Appendix - Callback Refnerence
  • Appendix - RSS and other XML Formts

That's all for now. Hope this helps.

- Sam

RE: First Look at the Documentation Outline (#303)
Posted: 6/6/2002; 2:40 PM by Seth Dillingham
Modified: 6/6/2002; 2:40 PM by Seth Dillingham
Response to: 300
Edit | Reply

On 6/6/02, Donald W. Larson said:

>My only suggestion would be to add example code for each place that
>needs it from a beginner's point of view. Many texts on the Internet
>omit that very important aspect of using proper syntax.
>
>I know that request is a pain to implement, but i think it is a
>worthwhile effort at some level anyway.

There are code examples, but they'll be integrated with each of the sections/chapters rather than headings of their own, so there was no reason to list them.

Seth

RE: First Look at the Documentation Outline (#308)
Posted: 6/12/2002; 12:26 AM by Mark Morgan
Modified: 6/12/2002; 12:26 AM by Mark Morgan
Response to: 301
Edit | Reply
My two cents, worth both pennies:

There is no mention of developing new wizards. As an end user I'd like to see wizards be part of the development process. How is a wizard built? Is it a plugin? This can be important for developers building applications to be used by the less technically inclined amongst us.

Sam's comments about finding the templates bring up an interesting point. In Conversant there is often a particular way of thinking about how to solve a problem. For example, there are two sets of templates for most Page Types: the one that wraps the page type, and various templates that are generated by the page. (An example of the latter are the templates that control the look and feel of an Advanced Query Page's headers and footers.) Or controlling advanced functionality (like, date formatting) through macro coding instead of, say, by radio buttons in the admin system.

All this made doubly more interesting by the fact that nothing in that paragraph cannot be overriden by a plugin.

I don't know how much of this philosophicalism a developer needs up front to get programming in Conversant, but as an end user learning it was an important step in understand Conversant.

In my opinion, there is not enough discussion (from the outline header point of view) of the other two basic ways to interact with Conversant, via e-mail and through a newsreader. While Herald isn't available at least at the moment, the trimodal, we let you do it your way nature of Conversant is its greatest strength. For example, you have "Creating a Conversant Site" might be "Your first Conversation" to better abstract it from "website + cool features". I'd like to see developers from the get go thinking things like "hey, I could build a serious Yahoo! Groups killer in this thing!"

First developer to write that "give Mark a pony" plugin gets my undying gratitude...

RE: First Look at the Documentation Outline (#310)
Posted: 6/14/2002; 12:59 PM by Clark Venable
Modified: 6/14/2002; 12:59 PM by Clark Venable
Response to: 299
Edit | Reply
Seth and I have had occasion to discuss the performance of Conversant on a Mac vs. a windows machine with a high MHz processor. Would it be appropriate to discuss hardware choice, and provide some guidelines for what rocks and what rots?

Clark

RE: First Look at the Documentation Outline (#312)
Posted: 6/14/2002; 1:26 PM by Clark Venable
Modified: 6/14/2002; 1:28 PM by Clark Venable
Response to: 299
Edit | Reply
Some thoughts (from a non-developer):

Please consider including a section on intra-zone cross referencing between conversations (as for templates, for instance--one set of templates in one conversation, and then use the insertTemplate macro to maintain consistency across a zone.) Now, you may consider it obvious from the macros which exist, but it wouldn't hurt to make it explicit. There's so much to grok that I think you'll want to 'help' the developers in making certain connection.

Under Appendix-RSS and other XML Formats, you can now include a section on OPML! (since the addition of the new date macros).

Consider including a separate section under security for Transport Layer Security, so that a developer scanning the TOC would see that right away, instead of having to dig for it.

Consider section within CSS on limitations. Specifically, when order of css elements is important, it may be best to use an external stylesheet editor and not store the style sheet in Converersant. (please correct me if I'm wrong on this.)

Event calendars? (very powerful, I think).

Add Plugins-->Overview-->Community-produced (hopefully this section will become larger with time).

Something about pre-bound url's (/signup, for example). To be clear, what I mean is url's that yield a page without having to define it in the siteStructure.

RE: stylesheets (#315)
Posted: 6/14/2002; 3:33 PM by Seth Dillingham
Modified: 6/14/2002; 3:33 PM by Seth Dillingham
Response to: 312
Edit | Reply

On 6/14/02, Clark Venable said:

>Consider section within CSS on limitations. Specifically, when order
>of css elements is important, it may be best to use an external
>stylesheet editor and not store the style sheet in Converersant.
>(please correct me if I'm wrong on this.)

Actually, that's no longer true. There's an update to Conversant today with a major rewrite to the stylesheet editor, courtesy Greg Pierce. It no longer changes the order of elements unless you use the multi-field editor (which is no longer the default).

Basically, if you're using the single-field editor, whatever you submit is what will be served as the stylesheet.

seth

RE: First Look at the Documentation Outline (#316)
Posted: 6/14/2002; 3:38 PM by Seth Dillingham
Modified: 6/14/2002; 3:38 PM by Seth Dillingham
Response to: 312
Edit | Reply

On 6/14/02, Clark Venable said:

>Event calendars? (very powerful, I think).

We're not shipping Conversant with the event calendar, at least in 1.0. We will make it avaialble, but it may be an add-on, or it may just wait a little while.

>Add Plugins-->Overview-->Community-produced  (hopefully this section
>will become larger with time).

Well... no. That's not for the docs. We'll have a section on the web site for plugins produced by independent developers (so far there's only one that we've been told about), but that doesn't belong in the documentation.

(These docs are going to be mirrored between the web site, a downloadable web site, and a downloadable PDF file.)

>Something about pre-bound url's (/signup, for example). To be clear,
>what I mean is url's that yield a page without having to define it in
>the siteStructure.

Good idea, thanks. They're definitely not bound URL's (which is a message being displayed at a named URL), but I understand what you're saying. "Pages that come with every new Conversant site."

Seth

RE: Hardware and Operating Systems (#318)
Posted: 6/14/2002; 3:59 PM by Seth Dillingham
Modified: 6/14/2002; 3:59 PM by Seth Dillingham
Response to: 310
Edit | Reply

On 6/14/02, Clark Venable said:

>Seth and I have had occasion to discuss the performance of Conversant on a Mac vs. a windows machine with a high MHz processor.  
>Would it be appropriate to discuss hardware choice, and provide some guidelines for what rocks and what rots?

That's a good idea, but it's hard to just answer it plainly.

The hardware requirements are determined by a matrix with at least three vectors: traffic to the sites, complexity of the sites, and the size of the sites (number of messages).

Free-Conversant, and all the free sites it hosts (as well as the fairly large support site) are all hosted on a 600 Mhz Pentium III with 384 MB Ram. Dave Winer picks on me about how slow those sites are, but he doesn't realize what lousy hardware it's running on.

Our biggest server is the one hosting animalrights.net. 1.4 Ghz Athlon with 768 MB RAM. Crappy hard drive, though... I'd like to upgrade it but the customer's happy enough with the performance (2-3 seconds for most stuff, though his home page is actually slower than that).

My fastest mac is is a G4/450 running OSX. I'd never try to use it as a production system at Macrobyte, but it would work fine as a production intranet server for a smallish organization. Plus, it has a free version of everything one needs for the email interface, which makes it a very convenient system.

Doug Baron said that the reason Frontier/Win was so much faster than the Mac at certain operations was that the Win32 file system was an "order of magnitude faster" than the Mac's. Now that we have OSX that's no longer true, but the problem persists. Now it's because Frontier is very Mhz-dependent, and high-frequency processors are a lot cheaper and AVAILABLE in the Windows world than they are in the MacOS world.

I'd love to have the time and money to experiment. I'd take two 1 Ghz machines (1 MacOS X and 1 WinXP/2000/NT4), with the same amount of RAM, and totally optimize them JUST for running Conversant on Frontier. Whatever it takes, and that includes tuning (or disabling) everything in the operating system, other apps, and in Frontier itself. Then I'd run gobs of performance tests to find out which is faster.

For now, though, the rule is that higher-frequency processors and more RAM give you better performance, and that means Win32.

Seth

RE: First Look at the Documentation Outline (#323)
Posted: 6/17/2002; 3:41 PM by Samuel Reynolds
Modified: 6/18/2002; 9:51 AM by Samuel Reynolds
Response to: 312
Edit | Reply
> Plugins-->Overview-->Community-produced

FWIW, I was thinking about generalizing the 3rd party Plugins site (http://plugins.weblogger.com) to include plugins for both Manila and Conversant, instead of just Manila. Not much demand yet, but now that developers have their hands on Conversant....

Whether or no, a directory of plugins available for Conversant would be a Good Thing.

> Something about pre-bound url's (/signup, for example).
> To be clear, what I mean is url's that yield a page without having to
> define it in the siteStructure.

I think I'd prefer "reserved paths" or "reserved URLs" (and make sure the site admin can't overwrite them by creating pages with the same names!).

- Sam

RE: First Look at the Documentation Outline (#363)
Posted: 7/8/2002; 4:52 PM by Bradford Powell
Modified: 7/8/2002; 4:52 PM by Bradford Powell
Response to: 299
Edit | Reply
I wondering how one can even begin considering using Conversant without knowing more about interfacing with databases. The only thing in the outline that seems to mention this is Twine, which from other postings seems to be an interface between Conversant and a database.

Is twine part of Conversant, or exactly how does this fit in.

Brad

RE: First Look at the Documentation Outline (#364)
Posted: 7/8/2002; 5:12 PM by Greg Pierce
Modified: 7/8/2002; 5:12 PM by Greg Pierce
Response to: 363
Edit | Reply
On Mon, 08 Jul 2002 16:58:14 -0400, Bradford Powell wrote:

>Is twine part of Conversant, or exactly how does this fit in.

Twine is really separate application on which Conversant relies.

Twine provides application programming interfaces ( APIs ) for storage and other services which Conversant uses.

The key to Twine is that each of it's APIs reside on-top of "engines", which are essentially plugins to interface to actual databases. The default engines store data in Frontier/Radio table structures -- but other engines could also support anything from storing data in the file system, to mySQL, or whatever other datastore is desired.

This makes the actual data storage invisible to Conversant, so the "engine" used by a particular zone or conversation can be changed w/o effecting anything running on top of it.

Does that make sense? It's hardly full documentation, but that's the general idea.

g.

RE: First Look at the Documentation Outline (#365)
Posted: 7/10/2002; 5:05 PM by Bradford Powell
Modified: 7/10/2002; 5:05 PM by Bradford Powell
Response to: 364
Edit | Reply
Thanks Greg:

Yes. I just wanted to note whether a SQL database can be used with Conversant. As you say, it can, and Seth has indicated that Twine is part of Conversant so, it can be a complete package for those who have or want to use SQL databases.

Brad

Messages: 14.
Pages: 1


 
© 2002 Macrobyte Resources. All rights reserved.