Forum OpenACS Development: Prelim Design Doc for Developer.OpenACS.org
DISCLAIMER: This is a draft. Any typos or horrible mistakes are my fault and I don't care. Because this is just a draft. Although I did look it over so I don't look like a complete fool.
Developer.OpenACS.org will be a central location for developers to access OpenACS code and documentation. It will be organized according to package and will provide decentralized administration of packages as well as a simple, consistent navigation framework.
This section has been designed with Tigris.org as its primary model. The approach is to create a consistent and standard number of elements for OpenACS module documentation, access and maintenance.
Each package subsite will have:
- Package Home
- Download section
- SDM page
- Individual Bulletin Board
Currently, OpenACS.org is the sole location for developers to access and download the code. Since 3.2.X does not have a feature such as APM, a user downloads the entire code en masse. Documentation on the site is reasonably obvious but documentation for specific modules is difficult to find and until very recently non-interactive.
With the development and release of OpenACS 4, access to documentation according to specific package will be very important. This is because each package can be accessed and implemented independently of others. Furthermore, each package will have an owner or overseer conferred with the responsibility of maintaining the package.
The challenge with Developer.OpenACS.org will be to build a framework that provides simple and effective navigation of documentation, downloads, SDM access, patch submission and bulletin boards per package.
The Central Page is the hub of Developer.OpenACS.org. This is the index page and from here a developer will be able to enter any package's home page with a single click. In addition, there will be a unified bulletin board which will highlight the last ten )or X number based on user's preference) posts from all the packages. There will be a link to each package's subsite. There will be a unified list of the latest submissions to the SDM. Also, there should be a link to a page containing a complete list of packages where a person can download the APM with a click.
Each package will have its own subsite, preferrably with it's own URL served via virtual hosting (i.e. bboards.openacs.org, portals.openacs.org, etc.). Each package site will be organized similarly to those at tigris.org with tabs linking to pages within the packages site (see http://subversion.tigris.org). The motivation for Package Subsites it to provide consistent interfaces for the 30 odd packages and to organize the information in a coherent fashion.
Package Home: This page will be a micro version of the central page. It will feature information from each of the sections. The executive summary from the documentation page will be shown prominently so that people know exactly what the pacakge does. It will have links to the 5 most recent bboard postings. There will be a review of the most recent submissions to SDM. And of course, one will be able to download the package directly from this page.
Documentation: This page will be the entry point for documentation on each module. It will contain the executive summary of the package's documentation and links to the rest of the docs, including installation procedures, troubleshooting tips, etc. General comments will be enabled on each page. Administrators of these pages will have ETP privileges.
Download Section: This section will have links to the latest versions of APMs in CVS. It will have a very brief description of installation procedures.
SDM: This section will initially be a straight port of the SDM from a 3.x architecture to v4. See the current SDM for a sense of the functionality.
Bulletin Boards: Each package should have its own bulletin board so that all the questions and knowledge concerning it can be accessed in a single place. This is to augment the full site search with category searches. In addition, developers will have a place to seek an answer for and then ask a specific quesetion about each package. There will be a unified bulletin board elsewhere on the site where developers can access a full view of all postings.
That said, I like to have the main tasks, i.e., ask a question, report a bug, download latest version, etc... accessible directly from the package home page.
How about a single central forum, and simulate having separate sub-forums by programming the packages so that they set a topic field on all messages posted, and then only show messages with that topic.
So if you're only interested in one package or two, you use that package's forum interface, otherwise you go to the top level forum (which still accessing the same data all the time).
Most people do not classify their postings, and this will be less likely if we have one category per package...
Besides the technical description of the package I would have some non tech abstract (a sales pitch). I would also have a list to "white papers" that explain it in more detail (when they are available). Finally I would have some distintive presentation between packages, like in jakarta.apache.org, where each project has its own logo, and to some point its own personality.
We certainly shouldn't forbid anyone to work on making his or her package unique but I don't think it should be a policy or even that it should be encouraged.
You are right that packages are developed in a few months at most but they will be around for a while, and they will need new features and requirements... not only simple packages like calendar but imagine the more complex like CMS. CMS could become an entity in itself, with 3-4 develpers working only on that.
Anyway, as I said earlier I do not think that individuall bboard is good idea, we do not want to atomize the community. I was just suggesting a logo and some cathy phrase on top of the page, particularlyt for those packages that can be more relevant.
I mentioned Jakarta since I understand it as a number of projects with a common vision and community. The personalization empowers the people behind that particluar subproject. You might even find that a company wants to sponsor a particular subproject, they could put a small banner in *that* page...
Feature requests/bug reports are probably best handled through the (slightly enhanced) SDM. I guess that most modules contributions can/will be added to OpenACS CVS and SDM.
Tracking feature requests and commenting on them is already possible with the SDM. What we definitely need is better notifications on new feature requests and bug reports, maybe one that is partially integrated with the bboard. If we can link a bboard thread to each Bug or Feature, where the bug or feature description is the first message... that would encourage ppl to write nice reports.
It might be nice to add a directlink in the module admin pages to the appropriate SDM entry.
What we definitely need is better notifications on new feature requests and bug reportsWhat do we need other than finer granularity, perhaps? I'm signed up for alerts on the existing SDM and get e-mailed notices of bug reports and feature requests. Of course the wording to enable this - "I'm interested in this package" - isn't clear, many folks probably don't realize this turns on e-mail alerts!
Since it is possible to comment on BAFS it's already possible to converse to about them, though not quite as slickly as the bboard UI perhaps. The truth is that most bugs aren't very interesting conversation topics, and most features get raised in the bboards rather than the SDM ...
The reason I suggested having a bulletin board per package was in order to have a location for specific answers about each package to be asked. The hope would be that the person with the question would assist in organizing the knowledge that gets lost so often in the bboards.
However, I imagine that experience on the AOLserver lists has proven that this isn't the case. I also admit that often times people post to the most frequented or popular bboard, not necessarily to the most appropriate.
Since the bboards prove to be the most important source of information and full site search is not always the most effective means of getting that info, I suggest that within each package site the package maintainer (or whoever is given appropriate permission) selects threads that are relevant to that package. (Setting up internal links to other parts of the site is trivial.) Then each link gets a short description about why it is relevant for the specific package.
Taking the place of the package bboard in the Package Subsite will be a weblog for each package. The package maintainer, or perhaps team, then uses the weblog to track changes, commits, bugs, etc. Each log entry is enabled with general comments so others can comment on it.
SDM is still an issue, but I imagine it will be solved reasonably soon. Either we'll have an alpha or beta version of SDM available, or the 3.x version will be grokked to work with the 4.x system.
How does this sound?