Forum OpenACS Development: Response to How about an OpenACS wiki?

- i don't know much about wiki lineage, my experience is with zope
wikis, if a tcl wikis can support these features, i'm all for it. my
answers below are based on my knowledge of zope wikis.

- wikis are very open by nature. the key to culling documentation
out of a wikis is to organize the wiki and adopt some basic
conventions. there are a couple of options that spring to mind, one
would be a official doc wikis, which could house wikis docs that
have been reviewed (with restricted edit privileges) and have a
sandbox wikis for howtos, architecture docs, etc. another would be
to have a wikis. yet another is for each document(or doc collection)
to have a comments page that comments about the doc could be stored,
without allowing every user to edit the document. users would pick a
wiki name by which to edit and would note the date of their additon
(or this could be automatic for comments). they're are many options.
as an example take a look at

http://www.zope.org//Wikis/DevSite/Projects/ParsedXML/ParsedXMLIsNotXMLObject

notice the options at the bottom for history and comments.

to restate, some organization of the wikis and locations for various
documents, some basic conventions about editing. most of which can
be worked out later.

- i can setup notifications to a document author and a list of
interested parties, on document changes.

- noticing whats has changed about a document can rely on either
using a comment facility or conventions about editing.

- wikis are searchable. and can also have a heirarchial view.
see the following for an example.
http://www.zope.org/Wikis/DevSite/Projects/ParsedXML/FrontPage/map

i don't know that submitting a patch or bug report via the sdm is as
easy as editing a wikis or as easy to integrate into the original
doc.

- as i said in my original comment wikis can be edited via emacs
(via ftp).

there have already been books written using wikis as a development
structure.
http://www.zope.org/Members/michel/ZB/

which uses a modified wiki and structure text for the whole book.

all zope wikis use structured text as their format language.
structured text are just some basic structure to give a text
document so that it can be transformed into another format.

this is a reference for one version of structured text thats pretty
common (there is one other StructuredTextNG).

http://www.zope.org/Wikis/DevSite/Projects/ParsedXML/TextFormattingRules

structured text allows the entire thing to be converted to docbook
(4.1 xml), to html, or left as text.

doc book seems to be coming in vogue as a doc format
check http://developer.arsdigita.com/docbook/

but writing in docbook is also a learning curve, using structured
text is easy, doesn't require markup, and can be converted into a
variety of formats (and through docbook to others).

i'm not suggesting that the wikis be in any way official
documentation, but they can greatly facilitate the creation of
documentation, both by lowering the barrier for the community to
become involved in the documentation process and by easily allowing
documentation to be created in multiple consistent formats.

documentation should be centrally located. i don't envision the
wikis as official documentation but as a place for documentation
generation, and a road map and organization could easily be imposed
on them for navigation and to facilitate extraction. the current
scheme doesn't do much by way of centrally locating docs, (scattered
in file-storage, across threads in the bboard, in private emails,
etc).

an acs wikis could be written over the file-storage, but this
requires someone to step up and write the thing, and would probably
require a subsite till openacs.org switches over to openacs4.  i'm
just offering suggestions about using existing tools to help the
situtation now.