Forum OpenACS Development: How about an OpenACS wiki?
Part of the problem seems to be that all the installation/configuration instructions are terribly Redhat and Oracle specific. A newbie is going to get completely lost/discouraged in trying to figure out what still applies in a PG installation.
Adding PG specific docs are a good start, but I just don't see how we can do so without making the docs unweldy. It almost seems that we need to maintain a separate doc set for each DB. Further, each Linux distro is sufficiently idiosyncratic that we should document changes needed on each distro.
Forking multiple copies of the docs for each DB/Linux distro is simply a bad idea from a maintenance perspective, but the other alternative of having one-size-fits-all docs is also pretty bad.
I recall someone bringing up the idea of a wiki (what's a wiki?)for either OpenNSD or OpenACS at one point. I've never seen much use for one until now. If we had a wiki going, each of us would be have the means and the freedom to add/modify to the docs as time permits. The current discussion forum, and static doc set doesn't encourage nor allow someone who is feels like "spreading the word" to do so. E.g., the stuff I've posted recently about Debian packages and quirks ought to be in some branch of a wiki, not buried amongst hundreds of passingly related messages in this forum.
It seems that a wiki would be really useful and important to as part of the OpenACS project. A wiki, for us, would be to documentation as is cvs is to source code
Enables people who can't help much with coding to contribute
informal documentation which can later be used for formal
docs and is immediately available in the meantime.
Doesn't need to be integrated with rest of OpenACS web site or OpenACS software as long the entry point URL is there and it's backed
Can be another port or a sub-domain on same or different box.
used to the editing format, wikis seem almost magical, because they
help generate content so quickly.
i'm coming from a zope perspective, where all new proposals and
documentation are implemented via wikis. check out
http://dev.zope.org for an example.
if people are interested in this idea, i've setup an openacs
playground wiki with some skeleton information at
i've created it with anonymous writing capabilities, feel free to
edit it and play around with it.
i cut n pasted the dispatcher spec and did a little bit of work
editing the start of it.
if the powers that be are interested, i'll volunteer to setup an a
zope server with ZWiki on a subdomain, i can also restrict editing
to users of this site if access to the openacs.org postgres db is
given (via LoginManager). once its setup it requires no access to
the box to maintain.
the format for Zwiki is based on structuredText, which can be used
to generate documentation in a number of formats.
if some aren't keen on editing via the web, zope wikis can also be
edited via ftp (and in emacs via ftp).
i think that this would help alot by enabling everyone to start
contributing to the documentation.
I am working on couple knowledge management projects beside my studies and a really important step is the one from "rather unstructured information of distinct value" (bboard) to a structured and somehow certified stage (documentation).
If wimpy point doesn't really server that cause, is it tough to get wiki running on an openacs installation??? And could someone point to a "HowTo" then?
It's a system that fits well into some uses, but I don't know how would we use it for our documentation.
If somebody would come and edit the documentation that I put up, how would I know that it has been changed? And what has been changed? I still need to check for accuracy. It would be just as easy to file a bug report or feature improvement at the SDM, or even submit a patch.
If someone wants to write a new piece of documentation to contribute, Emacs or vim are much more comfortable than a textarea.
For example: The sdm should first have a place to input 1.) bugs 2.)feature requests for every documentation page. Then you could directly display the bug reports and the feature requests under each documentation page. A "quick" link under the bugs and feature requests of one documentation page would lead directly to the appropriate input fields at sdm ...
When someone has closed the bug or realized the request the "comments" can be deleted from the doc page. This way you don't lose control concerning verification...
So - give things obvious names and stuff them into file-storage. File storage supports comments so people can comment on contents. If you want to let other folks edit the file, just give registered users write permissions.
No, it isn't as convenient for editing as a wiki, not by a long shot. But being able to add comments without editing the file is nice.
We all know that file storage as it exists in openacs3.2 sucks in many ways (can't change permissions on folders, etc). If you've never used it now's your chance to see just how bad it is first-hand!
(is 4.x any better? I've heard rumours of poor performance but how about the 4.x file-storage UI? Can you actually do the things people want to do with files?)
If we were to establish a wiki I'd much rather do it using something that would run on this box rather than elsewhere. All important shared information about project should live in one place.
I share Roberto's concern, too. Wikis can certainly be just as hard to dig around through as a forum. That's why files posted for comments and possibly editing by others seems like a good approach for things that we actually want to see written down and and eventually worked into the doc set that ships with the package.
So - which of you wiki fans is going to write a wiki module for OpenACS 4.x? It could be just-another-interface to the content-repository, you know?
Could also be possible to enhance existing Wiki concept by using some of the other features available within OpenACS eg to provide auto-cvs
versioning etc and/or use the journalling stuff in kernel and mail notifications to solve some of the very real limitations of wikis that have been mentioned.
But I thought Edmund's suggestion was more about something immediate to help structure snippets of information people can contribute faster and easier than they could contribute to fully structured OpenACS.org web site or formal documentation - with things that are less ephemeral and unstructured than bboard postings. These can then separately be re-organized into web site and formal documentation (via cvs, sdm, file storage, whatever) as and when time is available.
Anyone with the skills to write a new wiki module for OpenACS right now is likely to be busy on porting etc. Likewise people too busy
to either hunt down info about what's going on through bboard on the one-hand or re-organize it into more structured and stable form on the other right now.
Agree it should be on the same box:
a) To ensure it's backed up along with the rest (I sure hope the rest is being backed up daily
b) To emphasize control by core team as part of single project.
(Someone from core team should be in charge of it - the
"RecentChanges" link shows "what's new" to solve Robert Mello's
problem for knowing what's changed when doing more structured
documentation, and for re-organizing etc by whoever manages it).
Kapil's "sandbox" demo has shown that it can be done very quickly and easily.
So why not just install that under separate subdomain on Ben's box
with handover to Ben or whoever Ben designates rather than wait for a properly integrated new module to be developed? Label it clearly as
an informal work in progress to avoid confusion with "official" info.
Presumably doesn't need root access for Kapil to just install it on a temporary account on main box with link from www.openacs.org to something like:
BTW the "structured text" initially *looks* no easier than writing to text box like current bboards. But once you start it turns out that you can format and link *much* easier than by adding HTML tags (and of course can still use favorite editor and paste it in).
Links can also of course go between wiki and bboards as usual.
I merely through that out because I've heard fans of wikis gush and gush over them and wanted to point out that a wiki-like UI on top of the content-repository wouldn't be that hard to write. Someone should do it - after the port's over, of course. As you point out, a wiki-like package integrated with OpenACS4.x would have some real advantages over simpler implementations.
I think Roberto's concerns are valid, though ... I haven't really heard a good response. Someone (and I think he's thinking it could end up being him, which is probably why he's concerend) would have to mine the wiki for stuff to put into docs later.
I would much rather have Edmund write up his information on Debian packages as a short doc and file it with a nice, expressive title rather than bury it in some wiki somewhere. Among other things this would encourage him to take the time to structure the information in a reasonable way.
Incorporating other peoples efforts at writing decent doc pages - even if they don't do the SGML part, just the content part - will be much easier than mining a wiki for those hapless souls who've offered to help with documentation.
- 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
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.
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
- as i said in my original comment wikis can be edited via emacs
there have already been books written using wikis as a development
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).
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
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,
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
I'm not necessarily a fan of wikis, since they can end up an incoherent mess if the users aren't careful about maintaining structure. However, it feels like we need a better way to gather together documentation.
The trouble with writing a more formal document is that it requires more energy to do. This is good in that it forces thought. But it's also is bad in that some snippets of info are too small to warrant a full-blown document. So where do we file away stuff like this so that others can find it? The other nasty about formal docs are that they take time to do properly, and this increases the entry barriers for people who have something useful to add, but don't have a lot of time.
The nice thing about a wiki is the communal aspect to things... people add/modify stuff as they can. With revision control, it would really be very similar to cvs.
Short of a wiki, I'd be happy with any kind of system that encouraged proper categorization, and collaborative updates and maintenance of docs. Even a decent threaded BBS could do this if were culled of old/irrelevant stuff occasionally.
Here's an example of why the current discussion forums aren't up to the task... I posted info about where to get the 7.1RC2 debs a few days ago. Since then, RC3 debs have been released, and they are available at a more fixed location. If I just posted an update to this on the forums, a user would have to sequentially read each message in the thread to see that more recent information was available. As a user myself, I'd much rather see what's relevant, and perhaps be able to see previous revisions or references to the content if I needed to verify something. Exactly like coding and cvs.
What would really be nice is if we had some kind of wiki-like medium where contributors could add tagged/categorized content so that it could automagically be turned into customized formal docs on demand by any user. Is there anything out there that will do this for us?
If I just posted an update to this on the forums, a user would have to sequentially read each message in the thread to see that more recent information was availableThe "new answers" link, while not perfect by any means, does help with this. That's how I find out that something new's been posted to a thread.
Really, it is just the same as the "add a comment" links at the bottom of the ACS pages-- but they regularly roll these comments and suggestions back into the main documentation, and then delete the comment.
The manual is structured to have only one page per main subject, so there are not too many comments about differing subjects on one page.
The source is available for download (info below), but I believe the same could be done with a hacked version of the comments system.
Follow the instructions on http://cvs.php.net
to check out "phpweb"
instead of "php3", and you'll have the source for the entire web site.
The PHP documentation is extremely useful and easy to navigate. The "official" piece of each document exhaustively fleshes out each function's syntax and usage, and the comments typically turn the page into a mini "how-to".
I've found this format to be as helpful as any online documentation that i've encountered.
"I don't think Ben or Don are devoting oodles of time to keeping the site alive (are you?). "
I'm not sure if that was meant to be a flame. Regardless, I can't defend PHP on any technical merit. It's got strengths and weaknesses.
Whether or not PHP sucks isn't this issue -- I do think the project has great documentation. (when the site works, that is!)
Each page thoroughly documents _what_ a function does, and _how_ to use it. The comments are the icing on the cake, because they more often than not tell you how to avoid the pitfalls of coding a site with PHP. I think that OpenACS could absolutely benefit from such a structure, because it promotes steady evolution of the man pages. (I can only imagine that when PHP started, the docs were horrendous, because of minimal community input.)
I have no idea how PHP docs are maintained (ie, is there a team? do individuals maintain certain procs and functions, etc..) Something to investigate...
It would be nice to change wiki implementation from CGI program to some more efficient implementation. But I belive we could start with CGI as well.
I see a flat presentation of a long list of comments. This looks surprisingly like our despised bboard style of presentation.
I even have to scroll to the end to see the last addition to the Wiki.
Now, if I say "edit" I get to edit everyone's posts in a text box, rather than just add one of my own. That's a difference. I would guess that editing other people's posts is normally considered poor manners, though, and that in this particular example is rarely done.
So this example is just a discussion forum in disguise. The formatting's a little tighter and you can edit other people's posts, other than there's no real difference, at least on the surface. There are some shorthand text entry conventions that make typing a bit more convenient, but nothing earth-shaking.
I'm not saying the easy-to-edit collobarative file model isn't a good one. It can be for some things. The file storage area of this site allows for collaborative files, it just doesn't include the easy-to-edit part. Downloading, editing, and uploading is a PITA and the Wiki notion is much more convenient.
I'm just saying that this particular example is a poor one. It is being used in a way that is only slightly different than the current bboard forum we have here.
I would *hate* to see a wiki started up that degenerated into yet another bboard-style on-going discussion ala the ExtremeProgramming example given above. That would simply be splitting discussions into two, unrelated portions of the site (or two separate sites). All pain, no gain.
Don, I agree with you that using a wiki to add comments to a page in the openACS is nonsensical. I also think that implementing a wiki for static HTML with good history would be pretty revolutionary. My guess is that wikis as a community interaction are here to stay; we should just figure out how to implement them.
excessive flameage to be sent Don's way... Now I will enter the
discussion and attempt to share some of the abuse that Don
has single-handedly taken on :)
I haven't used Wikis, but the descriptions given here don't
convince me that a wiki will enable us to do *anything* better
here at OpenACS. Even with a significant amount of time spent
looking at and porting ACS 4.x code, I'm still not comfortable
commenting on certain pieces of it. I don't believe that such a
tool would be useful at this point in time, where the core port is
still under way, and where we're still figuring out how certain
details will work.
The communal documentation idea seems a better fit once we
have a *solid* handle on all of OpenACS 4, and everyone has
tried installing it a few times and has constructive comments to
contribute, rather than random ideas.
My vote on the wiki: we shouldn't spend core resources building
the architecture, or building the actual wiki content. Our time is
much better spent on the actual port, and answering these well-
formed questions that generate useful discussions.
My vote on the comments added to the doc pages: I think that's a
great idea. But again, what are you commenting on now? 3.x?
Sure, that sounds good. 4.x? What docs do people want to
comment on? There are discussion forums open to discuss
design, but there is little documentation to comment on right
About the uptime of OpenACS.org. OpenACS.org is running
OpenACS 3.2.4 (pretty much vanilla install). I've had to restart it
manually 3 or 4 times in the past year, and that was before I got
Arjun to install Keepalive on the box. OpenACS.org fails every
few months, and keepalive brings it back within 60 seconds. I
suspect the failures are due to driver issues that we've fixed over
time, and my failure to always upgrade to Don's latest patch.
We've had more network failures (ahem, Segnet) than we've had
OpenACS failures. So yes, OpenACS rocks.
I think this is a wonderful example of what a wiki can do for a collaborative community. If you login to the Mailman Design Note wiki, you will find that you can edit and lay waste to any page, OR you can just add a comment. Plus, and this to me is THE critical difference between a WIKI and our beloved bboard, and it's a difference that in the right community really powers WIKIs and has them really crushing our bboards, with a WIKI, casual users can do more than just edit/waste a page, they can create entire new sections of the website, or reorganize older sections.
For example, bboard threads are wonderful, but our search engine a bit restrictive. With a WIKI, a user of OpenACS might contribute by regularly spidering the site and creating a permutated index of the OpenACS site, and using the WIKI to host that permutated index as a WIKI page/application at the OpenACS itself. That contribution wouldn't require Don or Ben or Roberto to start or maintain, it would be self generated and it would be invaluable towards finding answers to OpenACS issues. (As an example of a permutated index, take a look at http://www.ilcso.uiuc.edu/Web/Documentation.html#A)
Ben, I believe the value of a wiki is that in fact you do not spend core resources building the wiki content, but you do enable the community to use community resources to create/edit/maintain content for you.
And I am pretty sure with the zope wiki the wiki engine maintains a history of each page, so if a kiddie comes in and wastes it, it can be reconstructed. Pages have owners that can delegate what others can or cannot do to a page. I think there is a diff facilility. And if there's not, well that's something to add to the ACS WIKI.
I have heard requests here and at the opennsd site that folks would like a sourceforge like projects page. A place to announce, discuss, and manage various openacs or opennsd modules. With a wiki in place, the community could create their own spaces as needed, without requiring the writing of an OpenACS sourceforge module. If you believe in ad-hoc self generated structure, the value of rapid prototyping and turn around from requirements to software and back, then I think a wiki would be a wonderful addition to the OpenACS and the OpenACS website.
Well, got to run and take care of the kids.
I never understood what a wiki is, but taking up Jerry's link, I guess I get the picture, somewhat.
I setup a user editable navigation a year or so ago. Then I never did anything with it. All that it has right now is navigation. What I had intended to do was to add the ability to register templates that would allow the entry and display of content in various formats. If a template was available at a certain position in the directory, the user could add information or navigate. I think I considered the term 'hyper-navigation'. What that meant to me was that index files served to tell the user 'where they were' and 'where they could go' and 'what they could do', kind of like a building lobby.
Anyway, you can add you own navigation, and try out that part at http://zmbh.com/testnav/.
-User-editable (and createable) pages
-Versioning, so you can undo damage
-The ability to restrict editing for certain users or groups
The problem with wikki is as much social as it is technological.
You can't just stick a wikki about any old topic out on the Internet
and expect all users to (a) not do anything destructive and (b)
know how to cooperate productively. Permissions exist to
enforce social behaviors and procedures. It's fine to say, "We
don't need our software to do that for us," but you'd better be sure
I see a wikki-like tool as being most useful as groupware, in the
spirit of persistent whiteboarding. I'm not sure whether it would
be all that helpful in documentation development; that's really a
function of the way people in the community decide to use it.
probably consider their use in other projects and how they have
solved similar problems/questions. the zope community is probably
the prime consumer of wiki technology and has tackled many of the
issues brought up here.
for some analysis and code check out
michel feldstein raise some good questions
at least for zope wikis i can answer
- zwikis are user editable
- zwikis support versioning with multiple undo levels
- zwikis support role based editing based on zope acls.
authentication can be done off external resources like the pg db
that houses the openacs user info. members without write priveleges
can be given comment only privileges.
if anyone in the community is intersted in seeing this in action,
i'd be happy to set something up.
The tool is already in place for us to document every API and make the OACS documentation all that we want it to be. To quote Nike, "just do it."
My advise would be keep it simple, do not use zope or wiki to create an acs environmet/userguide to ACS. This will only confuse users. I don't want to discredit the other systems, from an outsiders' point of vieuw I would say,... If the Openacs infrastructure can not even be used to create a userguide, why go for OpenACS? Who will read a users guide that requires users to become famliar with wikki or zope? seems like a chicken and egg question.
I feel there is an alternative to this issue. This has little to do with technology, but more with community buidling, based on the technology we have avialable. To be more specific, it's about people.
We need a /directory of people based on expertise re :
- Available time for paid consultation
- Available for free advise on simple questions, accesible via /chat or /tickettracker for a quick q&A session for problems that are a nightmare for newbies, and a piece of cake for hackers. (you couldset a time limit on the consultation)
- Daily editor of q & A on bboard, to cut trhough the clutter and eliminate duplicate answers. If you edit the topics on a regualar basis and weed out irrelevant speech, but stick to facts, you end up with a very readable userguide. Right now, a search in the forum database results in far to much detailed information for it to be usefull/understandable for end users / non hackers.
- Basic questions should be cut back to the Q&A module. That is what end users expect!.
Synchronise this with /glossary for those that prefer to be able to to do an A-Z inventarisation.
Right now just about every answer users may have has been answered at least a dozen times, in diffrent formats. The only problem is I am a dummy and don't understand what you folks are trying to explain. I don't speak your (tech)language, and more important. I am not interested to learn to understand it. What you guys make, must work for me as your client. No database will able to make that transition seamlessly without human intervention. You need a couple of people to make those translations.
That would be the volontary contribution from my part to the Openacs community, to set this in motion and act as moderator. We have great tool called member value. That could act as the fundament of the idea, as it tracks both real money and barter transactions.
Guys, we've got everything we need onboard, but only use about 60% to run our own show. What do you say?... who care's to help me to things in motion. I am dealing with end users on a daily basis and am developping a number of ACS project, and will be using the feedback and problem sets I get to make this work for my own service, but am convinced everybody can benefit from a consolidated effort. Why invent the wheel, because a system is to difficult to understand ? We've got 4622 registred users. I am sure there will be some folks that could help get things moving.
However, reagrdless of my opinions on wiki (which are irrelevant) there is a more fundemntal point, which I think Lars, Don and Ben were alluding to.
As with most companies, I'd be pretty suspicious of any that didn't use their own products (Remedy, by way of an amusing example). Whether or not wiki is good is kind of, neither here nor there... if we want something similar, then it makes far more sense to produce an OpenACS pacakge. Not only does this self-promote the platform, but it also allows us the opportunity to compensate for some of the shortcomings typically found in a wiki.
I'd also like to address Ben Koots comments. I think he's on to somehting there. I feel there is a space for some kind of organisation of knowledge and experience, but possibly not in as complex fashion as described. Your suggestion Ben, (forgive me for saying so) sounds a little bit of an admin nightmare. Perhaps a simpler organisation?
Also, I am very keen on finding out how newbies can be better helped and supported, but I think that the suggestions here are a little one sided. Not everything a development community does is for the benefit of freshmeat. A lot of what is being suggested here hints of 'more work for the non-newbies, less to do for the newbies'. I know I'll get flamed for that, but I think people are forgetting that it takes time, effort and therefore money for people to spend time helping newbies etc..
If I can use the Acceptance Testing effort as an example (don't I always), Everyone gets to benefit from the effort put in, the volunteers who helped test are essentially feeding back quality code unto the community... a good thing.... but we've ended up with the same core of people doing 90% of the work..
I'd be very interested in helping you out Ben and offering what assistance I can, however we need to think about balance.
Oh, and finally... are we all convinced the current bboards we have are insufficient?
I think someone in this thread said that newbies get answers from the community they can't understand or are inappropriate or have been asked before. Perhaps thats true, although I can't say I've seen that. This particular community is *really* active, and most people here seem more than happy to answer newbie questions etc...
Its more often the case that newbies original posting are next to useless. How many times does someone post up a 'I installed it and it doesn't work.. help!'? It pretty difficult to answer that kind of question, and people are reluctant to because it commits them to a series of emails and so forth to even get to the problem in the first place.
Is the answer perhaps a more structured question submission form? Perhaps something that required a minimum amount of information for questions to be answered? (machine, OS, log file extract etc)
I agree reading my description sounds complicated. I am using ACS intranet to administer this idea. Works great as long as participants use the available fuctionality. But... I am all for a very simple alternative. maybe it's an idea to activate the intranet on openacs.org for a start, and just start playing. Who knows what great ideas pop up. This my daily work, so it's no big deal to act as host/moderator or administer. I have time availabnle.