Archive of UserLand's first discussion group, started October 5, 1998.
Documenting The ODB
Author: Steve Ivy Posted: 1/25/1999; 2:30:45 PM Topic: Documenting The ODB Msg #: 2458 Prev/Next: 2457 / 2459
(Cross-Posted to DG/SM)There's been a pretty extensive thread about documentation recently on the Script Meridian list, so I'm pitching in with an idea I don't think has been seen yet.
For a while, Frontier had a really cool documentation tool, Docserver. Docserver has been replaced largely by the very useful Docserver website (http://docserver.userland.com), a dynamic website featuring documention in a standard format for most of Frontier's verbset. Very cool.
Lots of cool things have been done with Docserver, and the docserver database, including not only the docserver website, but LookUpVerb, (http://www.dallas.net/~gregp/frontier/lookupVerb.html), and Verbi (http://www.kalypso.demon.co.uk/frontier/verbi.html), as well as others I've forgotten.
But Frontier is much more than just verbs, as any Frontier developer will tell you. Much of Frontier's power lies in the various frameworks and suites which build on the Object Database and the rich verbset Frontier ships with.
One of the things which I still do is dig through scripts, tracing where various bits of information are stored, working to understand the structure of the ODB.
This longwinded windup brings me to my proposal: Documenting the ODB.
The ODB is rich, the ODB is vast, the ODB is confusing. There are a myriad of locations in the ODB which are important to understand in order to make the most of the website framework, system scripting, content management, etc.
So- my proposal is that, in similar fashion to Docserver, we begin documenting locations within the odb. We don't have to document ALL of it, necessarily, especially as I imagine it's going to be getting simpler as Frontier 6 evolves, and functionality is moved out of Frontier.root and into GDBs. Ideally we could have ODBDocs for both Frontier.root and Nirvana's various GDBs.
A couple ways of doing this:
- The Discussion Group. Start a new DG just for this project, Or even each DB. Each address/table gets a thread (granularity needs to be addressed on a per-location basis.) Just as Dave and group have proposed for answering Frontier questions, various members of the community could comment on a particular location, gotchas associated with changing the contents, useful tips, that kind of thing. Someone could compile/massage the original post until is took on some semblance of completeness. This would not necessarly have to be a Userland-hosted DG, but likely they would be the natural place for it.
- Script Meridian. The SM list is alive and well, and Doug Brewer has a respectable searchable archive going. The same approach could be taken on that list as could work on the DG- one post to get things started on a particular location, and the thread be used to work out the details / important points.
There are undoubtably more / better ways to do this, but I thought I'd throw out a few ideas and see what you, the community and UL, think.
By way of testing I entered a few random ODB addresses into the SE. Only those with direct applicability to Nirvana or the website framework got meaningful hits. I think this would be a great opportunity to develop something like docserver for the ODB, where someone could enter an address into the SE and find immediately a post embodying the collective experience of the community on that topic. Or, go one further and write an xml-rpc interface to the SE specifically for ODB addresses.
Thoughts?
--Steve
There are responses to this message:
- Re: Documenting The ODB, Dave Winer, 1/25/1999; 2:40:08 PM
- virgin.root, Dave Winer, 1/26/1999; 8:56:39 AM
This page was archived on 6/13/2001; 4:47:34 PM.
© Copyright 1998-2001 UserLand Software, Inc.