Forum OpenACS Q&A: OpenACS review: How might we improve this site? How can we support our community?

Now taking suggestions for making this site be more responsive to our
community: developers, users, marketeers, and purchasers of OpenACS
related services.  This review is gathering suggestions to improve
this site and our organization with the overall goal of improving the
OpenACS: usability, functionality, recognition, and brand name.

Please be specific whenever possible.

My own concerns:

0.  OpenACS is not the wondeful, easy collaborative toolkit I would
like it to be.  It has currently falls short in terms of site search,
documentation, and ability to organize or reorganize new content.

1.  It's actually rather hard for developers and users to find
information regarding OpenACS initiatives: what it's good for, how to
install it, how to use it, how to administrate it, and what's wrong
with it.  In short, forums may not be enough.  Perhaps other
solutions such as wikis, faq-o-matics, search-engines, peer rankings,
or automatic rankings of most read articles should be implemented.

2.  It's also hard for developers and users to participate in the
company, especially regarding the formation, discussion or, and
recruiting for new initiatives.  Using forums as they are now, the
announcements and discussions are lost over time.  Using forums as
they are now is not sufficient for project organization: what gets
done, why, by whom, and what the current progress is.  Perhaps we
might use sourceforge, or create or own.  Use freshmeat or create a
similar ACS page.  Maybe we should use wikis for brainstorming and
project organization.  Maybe we should create more forums.

3.  ACS is rapidly becoming non-buzzword compliant.  More
importantly, it's hard to address the current or tomorrow's solutions
with today's ACS, and it's hard to imagine the community as it is
now, addressing these concerns in a timely manner.  Example.  I'm
working on an XML-RPC interface to site-wide search.  Ooh.  The pain
of ns_xml, tcldom, and my own ignorance.  It's been a four days now,
and it's finally coming along.  Four days for xml-rpc may not be too
bad.  But to contrast, in C# and .NET (and there are presumably Java
solutions), webservices are a trivial addition.  As in it's only a
one-line change to your source file to have your C# function/ASP page
available in webservice form.  It's also an amazingly simple one line
at a DOS prompt (C: wsdl <url>) to generate a C# proxy class that
lets you call into someone else's SOAPified webservice.  To get back
to the issue, it's an awful lot of work for one developer to create
an XML-RPC or SOAP interface as easy as the ones enjoyed by Python or
C# users.  It would be impossible for this developer to create the
equivalent wsdl/tcl tool.  But it would be possible for a community
of coordinated ACS developers to do so.  What new problems should the
AC be addressing?  What should we be doing to get solutions in a
timely fashion?

4. today is okay for developers, not so good for
marketeers.  Do we need the content available at say, Zope?  Do we
need the look and feel of a userland?  How do we get PR?  How do we
become authorities in the sense of having members of the press
calling to get our views?  How do we get the gillmors and spolskys to
use our technologies?  How can we help the petreleys install our
systems?  How do we get distributed with Red Hat, Debian, etc.?
Would it be helpful to create a website design committee?  Or create
various known organizations with missions to evangelize or help out
the press?

I don't have any sure answers for any of this, and I don't know how
to generate consensus among 2500 or more members.

I would like to suggest that it's time to organize more formally,
with steering committee and with charter and bylaws that discuss
procedures for voting, for changing this site or the procedures
behind it, and for creating suborganizations with specific missions:
new initiatives, recruitment, documentation, pr, marketing, tools
integration, partnering, etc.

What do you think?

These are some things I can think of
  • Some kind of "work-force pool" could be arranged, allowing developers, and what have you, to enter their capabilities, availability and where that person can express what s(he) would like to collaborate on so that the community at large can visualize the overall will to contribute
  • We might create our own (or start utilizing an existing) IM tool. I really think collaborating developers can communicate faster and more concise this way.
  • Let comunity members candidate for a place in a steering committee and let the comunity select a number of them through votation.
  • We definitly ought to write a complete set of user documentation, both for 3.x and 4.x. A user or an administrator of a fresh OpenACS site should be able to find out how to go about doing stuff...
  • Last but not least; a search-engine is a must, and what you have demonstrated so far, Jerry, is looking promising!
Oups! I forgot to close the list:-P

Fixed it...
I would like to propose a more complete framework for documentation since having excellent explanations for the system will do wonders for its adoption and use (among current openacs hackers and others). I will post a more complete idea of what I'm talking about (after I speak with Pat Colgan, my colleague at Musea and a guy with really good ideas) but here are some initial ideas:

* The first and most important (i think) aspect of a doc is the Executive Summary, which the Big Picture tries to fulfill but generally screws up. This should explain the functional and technical aspects of a module so that an OpenACS hacker, a newbie hacker, and a totally non-tech person can understand what is going on. This is the most difficult part of documentation, but once you get this part right everything else is easy.

* There should be a a doc module that uses the DB. This is important so that elements of a doc can be posted in various areas, i.e. Exec Summ can be posted on a list of summaries for each module, the data module can be listed in another area with other data models, etc.

* There should be an element of a Wiki there so that people can collaboratively work on these docs. For instance, some people may not be very good at writing Executive Summaries so that everyone might understand. It would be nice if other members of the community can help make these docs more accessible. An "edit this page" element would be great for this.

* That we or a subset (Roberto and Don come immediately to mind since they have experience) establish the *essential* parts of documentation. So that a person writing documentation, for instance, knows that they have to include an Executive Summary, a data model and installation instructions at the very least.

These are my initial suggestions. I'm sure others have other points to fill out the proposal more completely.


It's been fascinating reading these discussions recently.  I hope that good answers are found.  I shall now diverge for a minute on the ideal solution to the documentation and general site-management problem that has been discussed.

What's missing from the toolkit/site?  The concept of "content", separate from the concept of "bboard post" or "faq question" or "faq answer".  In short, the (Open)ACS 3.x workflow generally allows creation (of comments, faqs, bboard posts) but little beyond that; there is very little moderation, editing, and no promotion/relocating.  It has been pointed out before that the great thing about the ACS is that it is user-centered; principally what ties all of the modules together is a common notion of user-id, the wonder of "single sign-on" across different modules.  This is great.  But it doesn't go far enough.  Content, once created, never migrates, is never re-used, and that's the problem.

Why should content migrate?  So that it can be saved, relocated, or expanded upon.  We have seen lots of great discussion here recently.  Why?  Because everybody is empowered to discuss.  It's easy.  There's this nice "Submit" button just begging you to talk.

A lot of the discussion has asked for better documentation.  We have seen a bit of that, but less.  Why?  Because fewer people feel empowered to create new pages.  You can send something to Ben.  But there's no nice "edit this page" link (essentially what Jerry is asking for w/ a WIKI), no clear way to go from "wow, that's a really great answer to that question" to "now there's a new page on the site making it easy to find that great discussion when browsing".  People can (and often do) write up what would make great webpages right here in bboard.  But it's a bboard post, not "content", so it eventually gets lost.

FAQs are asked and answered, only to be asked again later because the answer has become buried.  Because the question and answer in bboard can't be migrated to a FAQ list somewhere.  Because it's a bboard post, not "content", so it eventually gets lost.

What's needed?  Some system for promoting/reassigning/relocating/reusing content.  If I ask "What is OpenACS good for?" and Ben writes the best answer ever, a moderator reading the post should be able to click on a link to move the Q & A from bboard into a FAQ.  A group of FAQ maintainers should be able to refine the content appropriately (perhaps asking the original author for permission, or perhaps just crediting his original comment w/ a link back to the bboard).  If the FAQ answers just the question Ben needs answered when he's putting together an "about OpenACS" page, he should be able to include that content into an article at /about/openacs too.

In short, it's not presently easy for somebody who has something to say to do more than write a bboard post.  If it was possible to promote that bboard post to some more permanent status (FAQ, manual, news, whatever) with moderation/review/editing, it would be a lot easier to do more than just talk about what's needed; talking about OpenACS could be transformed into creating business-level documentation via a bit of moderation and editing.

I believe CMS and the content repository are attempting to solve this problem.  It's a tough problem.  You don't need a steering committee nearly as much as you need content moderators; unfortunately, the software must first develop excellent support for such moderation, so perhaps a steering committee will do in the meantime.  But, if you have some free time, it would be great to work towards making the notion of "content" as instilled in the system as the notion of a "user" (or party) is.  There's a base there now in 4.0, but I think it needs some more work to really empower easy shared website creation and maintenance, and it would be a great direction to take OpenACS in.

Nothing here is new.  WIKIs tend to ignore the concept of a user in favor of the concept of content; it's not easily relocated, but it is easily collaboratively edited and linked to (I dislike the lack of structure and control, but still find quite useful). does a pretty good job, since "messages" can be featured as "stories" or anchored w/ human-readable URLs.  Unfortunately both systems are essentially single modules; I'd love some examples where content has been treated well across an entire system, where I can go hit a website and write something that somebody else can decide to use elsewhere on the site.

And finally, I apologize for being all talk - I have the time for a bboard post now and then, but little more.  Happily, aD is once again taking up most of my time.  :)


Let me address the issue of documentation first, then I'll go on to the other points.

When I wrote the initial documentation in linuxdoc (later moved to DocBook) I did it because I wanted a way to export to various formats easily, and because it's easy to index and link things together.

The source for the documentation is available. You can just grab it and modify it, then send a patch. A wiki would be cool, but since mostly it's only me managing the 3.2.x documentation, _I_ don't have the time to wander through a documentation wiki looking for changes and then auditing it for quality. It just wouldn't happen.

Now, for writing _new_ documentation rapidly, then we may have a use for wiki there. For creating a new project, I don't know how a wiki would help, really.

0. I'd have to agree that content is hard to move (which hopefully will be improved once we start using CMS and the content repository), and you've being doing a great job of discussing the search possibilities in another thread.

Do you want to start a "OpenACS Search" Project? If so what do you need? How can we help? Tell us in plain terms. We'll continue to do our best to support the efforts of community members, to the best of our abilities and available resources.

1. This could be well addressed by creating a and improving the documentation, no? I haven't created a site because I don't have the time currently. I'd love to see it happen though.

2. The combination of file-storage, Wimpy and bboards has given some great results without the need for a wiki. Anyone can know who's doing what by looking at the OpenACS 4.x status page, which is constantly updated. Another option is that we could use the Groups functionality of 3.2.x to have separate projects with their own calendars and news items. We could have a "projects" page that would list the several projects. Would that be enough?

3. Goes back to the open source model. When a need comes a long and someone takes the lead and implements it, then a community gathers around it. We can't pass a decrete saying "YOU! Implement this" because nobody is working for anyone here (mostly). What you (and others) are doing with the XML-RPC thing is excellent! Keep it up. I got involved in this project 2 years ago because I wanted to run the ACS on my sites using PG. I got that. I didn't write documentation because I wanted to run ACS on my sites. I did it because it was a way to contribute back to the community, that has helped me stratch my itches.

4. The best way to discuss this (and all of your points here) would be (I'm sorry to say) in their own threads. Balooning everything into one huge thread won't cut it.

Regarding committees and bylaws and all that, I'd like to see other open source projects that do that and are successful.

Instead of "committees", I'd like to see projects (a 'documentation project', a 'PR project', etc.) Instead of a charter, I'd like to see leadership. Instead of formalities, I'd like to see commitment and fostering of new ideas.

Do you want to start an OpenACS-related project? Tell us what you want, and what would you like to do (in a new thread). Do you need a (just an example) domain? Do you need CVS? Do you need a new bboard?

Site is fine - content is good - Templating and CMS dicussions and pointers greatly appreciated.

More work on these would be great.
Is it appropriate to also discuss the other end of the scale - beginners?

Having recently helped some-one through the teething stages - getting everything built and running - I'd say that the first step after that is the hardest. And I wouldn't be suprised if there are some people who build and then find it gets too hard, and give up.
The standard build gets you to a log-in page (necessary and useful) bu t it is not immediately obvious to a newbie how to get a nice index page up (such as this site). Not that its difficult one you've integrated the ACS/POstgres/AOLsever model into your design thinking ... but how do you get to that?

It's a pretty steep learning curve at the beginning, just to understand the broad framework and the separate functionalities, and thats layered on the additional complexity (for many prospective users) of understanding the way to use database backed sites.

There's tendency (among beginners) to start altering code in core tcl scripts rather than using the set-ups, and pretty son everything is broken!

The Book is a great start, but like much of the documentation, it focusses on the data-model, and the uses that can be put to,rather than the getting at the functionality implicit in the data-model. And then, for newbies, the issue is how to quickly design/ achieve results within the ACS/POstgres/AOLsever model.

Two suggestions - some howto type documentation at a module level - I found that starting with one module (photodb in my case) on working through was very instructive; it gave both rapid results and a good idea of the operating "framework".
And plea for some sample code - such as some of the OpenACS site, say or some simplified versions of other sites.

David, I couldn't agree more.

A while back, I suggested a primitive version of what you

And very recently, (as in less than an hour ago), we put the
wheels into motion to create an even slightly more primitive

It should be possible to use the FAQ module to pull together
bboard posts (which anyone can make), wimpypoint
presentations (which anyone can make), files in file-storage, and
any other document that has a URL. It's not a perfect system by
any stretch of the imagination, but it's a start.

I was going to work the code from the OpenACS home page into my little docmentation attempt along with the code from my own home page.

Is there a great demand for 3.x information? I dropped the ball on that because I was getting ready for 4.x.