Forum OpenACS Q&A: Code freeze in favor of documentation for 4.7

Hi all,

With the impending release of 4.6 and start of work on 4.7, and given:

- The very little amount of documentation we have, especially end-user
documentation, and that the amount of documentation in 4.6 has
increased/improved very little.
- That we keep getting more and more new code which happens to have
little or no documentation
- That if we want this project to have a future, we need new users to
be able to understand it.
- That even experienced OpenACS users find themselves asking even
basic questions because they can't find it documented anywhere.
- That we have several parts of the toolkit that need improvement, but
that code won't ever change because it's not documented and no one
wants to work on documentation (this has been described as "the
downfall of open source" as Jeff Davis mentioned in #openacs quoting
(probably) the BitKeeper guy.
- Knowledge about parts of the system (often critical parts) are
scattered along the brains of individuals spread all over the world,
isolating users and developers

I hereby propose the following:

* NO NEW CODE makes it into 4.7 UNTIL:

- User documentation has been written
- Package owners have reviewed and improved the documentation for
their packages
- We review, correct and expand the developer's guide

And I am _dead serious_ about this. How much longer can we afford to
go with the little documentation we have? I think no longer.

You have my wholehearted support, I think thats a superb idea.

And as a gesture, if you want to suggest a particular piece/package/doc I will happily complete it and contribute that way.
(don't give me anything way technical, Id rather do something for newer/less experienced users)

I'll rehash the "Documentation Status" document listing things that need to be written/improved, so we can assign it to people. The current problem is one of resources (it has always been).

People want to work on code because it's more fun. You can see things happenning and people giving you kudos for your work (recognition). So we've ended up with very few people doing documentation, but this needs to stop.

I'm confident that once 4.6 is released, we could solve our documentation woes in 4-6 weeks of committed time from the community. But I only see that happenning if we have a new-code freeze until documentation gets improved.

From there on, we set higher documentation standards for accepting packages into the OpenACS CVS tree -- namely, your package needs to have documentation before it can be considered complete, no matter how well it works.

Actually Roberto I made a suggestion on another thread a moment ago about a good newbie level overall introduction that say things like what you need to know, or whats not important initially, how to do the basic things and so on...

I could take that on if its useful, unless there's a higher priority

Collapse
Posted by Dave Bauer on
Roberto,

I think this is a great idea. We have some plans and an initial outline for improved documentation linked here: http://dev.openacs.org/projects/openacs/developers/todo

OpenACS works, people are using it to build web sites. 4.6 is a big release that fixes many bugs. To improve the system we really need better documentation. This will even help core developers to improve systems such as permissions by gaining a better understanding of what the goals of OpenACS should be.

We need to look hard at the requirements docs that we have, and see if those are still the requirements we want. If they are we need to bring each package up to the functionality that was originally planned. Otherwise we need to redfine the requirements for the needs of current and future OpenACS developers.

I sympathise as to some degree its the same for testing. Although its easier for newer folks to get into testing than to doc up stuff they've just encountered.

But as for your last point, perhaps we should consider checking the documents as part of the acceptance test process.. i.e. documentation bugs for want of a better term

Collapse
Posted by John Holroyd on
Simon, I think that would be an excellent idea, perhaps in the how things are done section you could have use an example web service. Showing how from install things get done, and the configuration of a few of the basic packages, like bboard and news and their integration with the main site using the template system.
I have been working on install docs for a win2k/oracle instance which is mostly a remix of Vinod's existing procedures and when I have tidied it up a bit I will send it the relevant honchos.
Collapse
Posted by Don Baccus on
What if we do something like declare November documentation month, and try to round up commitments from folks who can both write and know the code to blitz through and do it?

We can't really stop all code going into 4.7, for instance Collaboraid has a contract with the University of Heidelberg to work on globalization and they're already in the midst of it.

But knowing the Collaboriad folk and from what I've seen of the University of Heidelberg both understand the importance of documentation.  I'd be very surprised if we couldn't get some help from Collaboraid during a "documentation blitz month".

Would an approach of this sort work?  We've talked about doing something similar with bugs...

Don,

I don't know. I'm sure Collaboraid would help with documentation. What I fear is that it'll be simple for most people to claim (for themselves) "well, I have a contract/commitment to finish too".

Of course I realize that commitments are commitments, but our documentation is in such need of help that we must find a way to commit people to help with it, and then work so it continues doing well.

The danger of not allowing any new code is that those with commitments (such as Collaboraid) will just say "I'll just keep my own tree and merge it later on", so we lost that contributor.

The danger of allowing new code is that it can be claimed to come because of the commitment.

So perhaps a balanced approach would be:

- No new code for #period of time#

- BUT, if you need to commit new code, it needs to be accompanied by documentation work in _some other_ area besides the new code being committed.

How does that sound? Another question is, do you think a month will be enough? (oh, I think we definitely should do something similar with bugs)

Collapse
Posted by Lars Pind on
Much as I like documentation, I'm not sure what the right solution is. I'm afraid of documentation that gets out of date, or documentation that goes unused, and thus becomes overhead. So I'd like to have a discussion about the kinds of documentation that we need. It's not something I've thought a lot about, so I'm sure that there are others out there with more qualified opinions, but here are some loose ideas to start with:

PACKAGE DEVELOPER'S GUIDE

- We need a package developer's guide and tutorial for how to build "good" OpenACS packages.

It should cover things like

- how to use ad_form,

- how to design your data model

- when and how to use content repository,

- how to internationalize it,

- how to write proper tests,

- how to write your requirements and design doucments and the end-user documentation,

- coding style,

- API design,

- other standard services like workflow, notifications, attachments, etc.: When to use them and how,

- UI guidelines,

- etc.

This is critical, because it's prescriptive, so it'll improve the quality of all new packages being built, and at the same time make it easier for new people to get started on building applications for us. And it must get updated to contain the latest knowledge about best-practices. Therefore we need a maintainer of this document, who can get support from others, of course.

END-USER DOCUMENTATION

This is important. I think it would be a really valuable investment to come up with a simple framework for this, so online help can be invoked in a standard way throughout the toolkit. Perhaps something as simple as adding a "Help" link to the default-master template, and having a directory at package/www/help store the help text files. They should also have a consistent look and style, since they'll become part of the UI.

REQUIREMENTS AND DESIGN DOCUMENTS

These are important for documenting assumptions and design decisions. But they must be kept short and to the point, and let's not try to be too strict on the templates for this, since this seems to encourage people to put lots of irrelevant details in there. It can also be really hard to write your assumptions clearly, since they're frequently assumptions you've made without realizing. I like Joel's approach to specifications: http://www.joelonsoftware.com/articles/fog0000000036.html

DEVELOPER DOCUMENTATION

Service packages or subsystems like CR, notifications, workflow, form builder/ad_form, etc., need a document explaining how to use them. These also need to be kept short and to the point, and shouldn't deal with the details of the APIs.

Other developer documentation, like API documentation and such, should be kept in the code.

-

Hm, this list got long after all. I'm not too happy with saying "if you can't write documentation, you can't contribute". I think there is going to be an eternal problem, because it is intrinsic to the people and the process.

Perhaps we can change the attitude. I think there's a good chance that if we improve the documentation to a point where it's actually useful, then the more people start using it, the more people want to contribute to it. But we should refrain from setting expectations that are so high that they're not going to be met, anyway.

Hm. These were loose thoughts. I hope they were useful to some.

/Lars

Collapse
Posted by Jon Griffin on
I have a proposal for docs at http://jongriffin.com/static/openacs/OpenACS-documentation. It is a starting point and I believe that Roberto is modifying/adding to what I have.
Collapse
Posted by Don Baccus on
Lars ... I agree that we really need a package developer's guide such as you describe. I have two problems, though. You can probably guess the first:
  • Resource - who has time to do it? A document properly covering the items you discuss, complete with well-commented examples and toolkit references, is not a trivial piece of work. That's not a bad outline for about half of an OpenACS O'Reilly book. It could only be done with someone who has intimate knowledge of how the toolkit works. There may be as many as a dozen people in our community who have that knowledge but I doubt if there's more. If our community were more robust financially, it would be a good project to fund, pay someone for a solid month or so to put together a really good document. Perhaps I'm overestimating the effort required. Am I? What do you think? Any ideas as to how we can get something like this written short of paying for it?
  • If we implement some or all of our labor-saving ideas in 4.7, the contents of such a document would be obsolete before it was completed unless the writing of it were put off until these new tools are written. This is a minor thing, IMO.

Roberto ... when I suggest a "document blitz month" you can be assured that it would come complete with arm-twisting, begging, and personal cajoling from me. And of course yourself and I assume other leaders in the community. I would also, of course, commit to working on documentation myself.

If we just lock down the tree and implement a moratorium on code changes we may just find that no code gets written and, damn!, neither does any documentation.

I agree entirely with you in spirit, though, we need to do something to tackle the documentation problem, and getting a bunch of us involved working on it at once is a good idea.

Collapse
Posted by Jeff Davis on
I would like to volunteer to write the package developers guide.
I think the right way to do it is write a cookbook
style version and based on feedback from that work on revamping
ch.4 of the docs (I think a short howto style doc that is less
exhaustive than the current developers guide would be a valuable
addition in any case).
Collapse
Posted by Lars Pind on
Great, Jeff! The package developer's guide will be a work in progress, just like the code. If Jeff can get thr process started, I'm certain that I and others will contribute parts of it. But it takes a focused first effort to get it off the ground. Jeff would certainly be a very good candidate for the job. Thanks.

The second part of my point was to try to limit documentation requirements in some places. For instance, there's really no need to include data model or APIs in the documentation. There should be comments in the SQL file, and ad_proc documentation of the Tcl API for sure. But separate documentation should only document the big picture/idea type things, such as defining terms and how they related, e.g. "a portal consists of one or more portal elements, which are instances of portal datasources", etc. Let the data model file tell you the details. Code is documentation, too, as I believe is part of the XP approach to documentation.

So what I'm trying to say is also that we should prioritize our documentation effort, and focus on the most important one, the package developer's guide being an important candidate. If we ask for too much, I'm afraid that we'll get less and lower quality documentation. I think we all agree on that, but obviously the hard part is drawing that line.

/Lars

Collapse
Posted by Ben Adida on
Jeff,

You beat me to the punch: I've been trying to find some time here to write a cookbook documentation of package development based on forums and/or notifications (since we wrote these fairly recently and they have few dependencies).

Want to work on some of this together, or do you have a plan in mind already?

Collapse
Posted by Jun Yamog on
Hi,

The package developers guide is something that is useful. I think the "Things to remember doc" that I started should have been this way. Jon's doc is broken down into user roles, my doc is broken down to file extension. The things to remember kinda lost its steam like most doc efforts. I hope people can help me with it since some items (in dark red) are items I need help. I will be interested and will contribute to the package developers guide, but not all section. In particular "when and how to use CR".

Jeff,

I think you have stepped up on this issue. Here is a link to the things 2 remember doc in case you will find some pieces useful.

http://www.infiniteinfo.com/openacs/things2remember.html

Either I continue to maintain that doc or we dump it and make a better one. If we continue to maintain my doc and make a new package developer guide it would be nice to get some help in making the 2 docs consistent. Don't want to put something on the doc that is contrary to the package developers guide.

Roberto,

I think your concern is correct. I don't think it would be easy to do it in the existing packages. Perhaps new packages that comes in must have a higher standard in terms of docs. Also maybe if we can acknowledge the developers for putting in good docs. If we can give more recognition to docs, since most developers hack in the code to get recognized. Maybe we can get people doing the docs. We can start with yourself and Vinod, most older member know that you are the doc master and Vinod. But that info is not visible enough for new developers. Why not have a section or place that is more visible to major doc contributors like you and Vinod? Maybe new developers may want that recognition and start doing docs too. I guess the docs has always been a hard nut to crack even outside of OpenACS.

Collapse
Posted by Don Baccus on
Jeff has effectively parried my first concern.  Happy me!  Thanks, Jeff.

We really need one good CR package example at least ...

Lars, I agree with your other comments.  There's no need to include datamodel or API documentation in the documentation.  Big picture stuff is all a competent hacker needs to speed up their understanding of the code they're looking at, and we shouldn't burden our developers with requirements to provide stuff already found in the code.  I don't know if this is an XP thing or not, but I do know it's been true in much of the industry ever since I got sucked into it in 1971.

Collapse
Posted by Jeff Davis on
Don, Is there a good CR example in the code now?  news is small and
and could be made into a good example with some cleanup but I think the permissions stuff in news is a trainwreck.  Bboard, wp-slim, file-storage, etc all are a little too large and generally too
ugly to present as examples. News also does use the service
contract stuff for searching which would be a good way to introduce
both of those.

Jun, your document is useful and yes, it would be nice to have everything be consistent.  One thing I would say is I would like
to split out just the negative things and make it a "Common Errors"
document and take all the afirmative suggestions and incorporate them
into the developer doc.

Ben, collaboration would be welcome.  I have an outline in mind
but had not thought too deeply about specific examples (the
above on news was my first stab at it).  I will write out an
outline and you can have a look and see where we go from there
(and anyone else who wants to be involved is welcome as well).
I do recognize you are very busy documenting the APIs you have
already developed and writing proposals so I don't want to make
too large a claim on your time :)

I think there is an awful lot that can go on in parallel and people
should also think about taking a look at the api documentation since
that can (and should) be a much better guide to best practices
if we just take the time to document what we think people should
really be using.  The embeded documentation for ad_form,
ad_page_contract, and export_vars are good examples of what we can
achieve on specific important interfaces.  Currently about 1/3 of
the functions lack any documentation and about 1/3 have neither
-public or -private designations (which means we can't say "look
at only -public procs").  I would say there are also about 50
procs which should probably be deprecated (although not so many in
the core now).

Sadly I am completely focused on developer documentation and
hopefully someone will step forward on the user side.  I also wonder
if we should have a document oriented towards designers and
people who don't need to dig in the code but do need to understand
some aspects of the system (templating mostly but also how to
theme subsites, etc).  Skin halfway covers this ground
but is out of date and I think easily overlooked.

Collapse
Posted by Don Baccus on
Jeff ... I'll try to look at news soon, I think it is a good size for an example.  I'm sure it could be greatly simplified so I might take a look at doing that.  The notes package is even simple and is really only a demo package, if "ad_form'd" that might make a good example (I don't know if it uses the CR currently, again I'll try to poke around and look soon).

API documentation ... public/private attributes ... doc blocks ... this is another area where it might be possible to get a few people to agree to sit down and blitz.

Collapse
Posted by Lars Pind on
Not Notes, please. We don't need a package that's demo-only. I hate those examples that don't resemble anything in the real world. Much better to use news, which is simple, yet actually being used.

/Lars

Collapse
Posted by Jun Yamog on
I think a demo package is not that bad.  News is small, but does not make use of CR properly.  Sadly only CMS makes use of the CR api.  A small app say notes maybe ok.  Since I am involved in the CR section of the doc, I will see what I can do.

But I lean towards a demo package.  Simple, maybe 3 examples.  How to make use of CR, just adding content and retrieving.  Just like what I have done for ticket-tracker lite and another project of ours.  Then example 2, small app that makes use of CR folders.  And lastly another app that has revisions.

Actually if the demo package is a bad idea, I would take file-storage as the best candidate.  Aside from ETP, it was FS that thought me about CR.  And now CMS.  Of course if ETP 2 is here then we have an good app to study.

Notes does not use the content repository. It is just a very simple example package that shows how to define a new object type and use some basic oacs 4 features.

For that purpose a demo package has its place, IMHO, because it does not confuse the newcomer with tons of functionalities. Also it is a very good starting point for problemset-like assignments, e.g. "extend the notes package by one text field and write an upgrade script".

As soon as one understands the basic concepts it is certainly better to study a real package though. So I don't think a demo-only package for the CR would be necessary.

I'll sit down later today and ad_formize notes if nobody has done so yet.

Collapse
Posted by Jeff Davis on
I'm with Lars on the demo example issue.  Based on past experience
what happens if you use a demo package for this is that it does not
get maintained and ultimately breaks and no one bothers to fix it.
That's why I want to pick a real module.  I also think it would
be quicker to pedantify news rather than write a good demo from scratch.

I lean towards news since it is not entirely contrived to have it
support search and notifications (which I think are important to
cover, as it stands both the service contract stuff and
notifications are not well documented anywhere).

I have never looked at Notes before, but if it has similar functionality to Notepad at mail.yahoo.com it surely is a valueable and lightweight package. I use Notepad intensively!
Collapse
Posted by Jeff Davis on
notes is just like yahoo's notepad except without searching, folders, a nice UI, synchronization to pda's, and any personalized setting :)
Collapse
Posted by Don Baccus on
OK, it looks like news is our best candidate, do we have consensus here?
Collapse
Posted by Ben Adida on
news is probably good for CR demoing, although there is some stuff in news that isn't too pretty (as Jun mentioned). But if the goal is to demo CR, it's probably the best bet in terms of being not too large and generally tractable.

(When I was in the process of outlining my docs for this, I was thinking about using forums as an example, which is a simple package written after looking at many other packages. Also, that could extend into a dotLRN development tutorial with dotlrn-forums. However, forums does not use the CR, so if that's the goal, then forums is not it. It might be interesting to extend the news doc into a dotlrn-news doc... I'll see how we can make that work.)

Jeff: I was also thinking about notifications. It's a simple package that provides mostly a service, but also a few end-user pages, and makes extensive use of acs-service-contract. I don't think notifications would fit the bill completely, though, so it might be something to do in addition to news? Maybe what we can do is work together on an outline and presentation style, and you can work on news while I work on notifications to present two different types of packages?

Please pardon this longwinded post...

I respectfully request that subsite support be included in the News sample application and documentation (if it isn't already).

Subsite functionality is very important to me, so in my own self-interest I hereby volunteer to help code, document, or proof-read the sample application (especially with regard to subsite support) as the leaders of this project see fit.

While I am no expert on subsites, I did manage to muddle through the creation of a custom package (for internal use) that supports subsites and seems to function properly.  However, I based my work on the pre-CR Notes example.  Helping out with this project would allow me to give something back to the community while simultaneously upgrading my skillset to include the CR and ad-forms.

I had to make some design compromises based on what I perceived to be limitations of the core subsite code at the time (4.5 beta), so this would also give me a chance to make sure that my understanding is in-line with the current "best practices" of the community.

Collapse
Posted by Ben Adida on
Dave, great point. Subsite-awareness needs to be documented. I don't think you're going to find a wonderful solution to all the problems you saw, but certainly there are better ways to be subsite aware :)
I am really glad to see all this discussion about documentation. There have been some great posts here, and I'm thrilled to see people actually taking on documentation tasks.

I have to finish some homework for school, so tomorrow I'll post a summary of what has been discussed so far, with a set of tasks to be accomplished based on what has been discussed here and my understanding of documentation status.

I'd also like to work on the developer docs.

Jeff, regarding:

<blockquote> I think the permissions stuff in news is a trainwreck
</blockquote>

I would add, with no survivors. =) I do have a version of news which uses the default system permissions and eliminates all custom permissions.  Do I have permission to check that in?

Also, what about cleaning up permissions in general?  There are several packages that unnecessarily create custom permissions.  Has that been cleaned up for 4.6?  Or is this scheduled for 4.7?

Collapse
Posted by Jeff Davis on
Nothing has been done on news for 4.6, and since were past the code
freeze it would be morally wrong to try and get it in :)
We have branched 4.6 so you can commit on the HEAD and it won't impact
the 4.6 release (and if you get it all in and we can test it perhaps
we would could merge to 4.6, but I think Don or Janine would make that
call).
I'll check it into the HEAD as you've suggested... anything to avoid having to go to confession!  =)
Collapse
Posted by Jun Yamog on
Hi Rob,

Please don't forget the upgrade script for the perms.  I hope it would not be too hard.  We need to move the current custom perms already existing in a running system to the default ones.

I will probably look again at news when I get back next week.

Hi all,

I thought I'd post some further info in support of Roberto's idea of a code-freeze for documentation.

(Ok Don, lets call it a code freeze, with the exception of critical developments ;)

I still feel this idea is a good one, and I still think Roberto is right that if we don't address it now it'll never really get solved.

Just from the 'philosophical' perspective. We'd all agree that a serious bug is one which stops users/developers from using a package.

Therefore if the supporting documentation is sufficiently poor (or just plain missing Tut Tut), then surely that stops a whole raft of people (newer users in particuar) from using a package?

I therefore argue that poor documentation *is* a serious, release stopping bug....

But this is not just my opinion. As testing has begun I am getting contacted by many testers, all with exactly the same problem!

I can't figure out what this package should do because there is no/little/poor documentation.

I would of course like to write to each of them and explain how it works and so on.... but there are only 24hrs in a day ;)

The feedback I've had from almost all testers is that the documentation is not good enough, and is severely hampering their ability to test..

I suggest thats a pretty bad (and persuasive) situation.

Ok, even if we don't agree on a freeze (and I still think short-sharp-shock is the way to go) then can we at least agree that in future. *No* new code will make its way into the base distribution in future without sufficent documentation?

There really is *no* point in bunging in code that isn't complete and doesn't have documentation. All it becomes is an excercise in self-publicity and ego building, without really sharing anything of general use. If we keep putting forward software that only the 'experts' find useful then this community may as well become a 20 man outfit.

I realise there's some philosophical view points in this community that it should remain a primarily 'developer oriented' community, but its just plain wrong, and breaks down when you try and comunicate/share material with your peers and colleagues (the whol point of open source inthe first place).

Its impossible to collaborate if we tie peoples hands in this way....

I realise ther is no obligation for people who submit to provide all this, after all we should be grateful they are sharing anyway, but Open Source is a two way thing, and submitters benefit as well as donate... and think how much more we can *all* benefit for that sake of producing so supporting communication.

Hear hear!

To tell you the truth, I hardly look at the docs on my 4.5 installation because they are oftentimes incomplete or simply incorrect.  I usually just jump into the code with my good friend 'grep'.

From testing some packages and reading through several older threads I get the impression that some packages will not be supported or merged into other packages in the future. For example survey / simple-survey. It wouldn't be clever to document packages (in this case simple-survey) which will be deprecated. Therefore it would help to first have a list of packages that will / won't be supported in the future.
David, I beleive Janine is in the process of doing just that.

As for 'grep' as a documentation tool, I also rely heavily on it.. but that is definately no way to inspire new users ;)

And of course to 'learn-from-code' does require at least 'some' good introductory docs.

To be honest, in true XP fashion, I'm not convinced of the real need for tech docs and design docs (my opinion).

90% of what people need docs for is when they're new, unfamiliar. They don't want to know how tables are joined, or how request processors function, they want to know how to build a web app, whats important to know, what they can do without knowing, and what the 'process' of using the system is...

As a relative newcomer however I would have to say that I really like the 'deeper' documentation because by reading that I can truly LEARN something. Documentation is of course vital - the openacs docs in my experience have been excellent - and I personally would be sorry to see the educational stuff replaced by surface how-to's. I think both have an important part to play.
Richard I agree (although I don't share your opinion on the quality of the docs) they are both important... but....

'it feels like butter thats been spread over too much bread'

There's no getting around it. The resources aren't there to cope with everyhting to the same level. My argument therefore is that we focus on docs that help the people who need it most. Newer users, non-techs, techies with less experience.

The reasoning here is that I think everyone would accept that once you know OpenACS well you can make progress rapidly and do many usefult things....

But.. and I guess this is virtually a design flaw, its learning curve is way to steep initially. The initial mountain to climb is too steep for many...

I recall when we ran a bootcamp for aD (with Eve, Dave and so on attending) that they themselves barely had a grasp of it all!

So, we either flatten the curve, or we provide good tools (docs) top help people up it...

I'm kind of saying, 'Don't write docs for me, I;ve got the hang of it now... write them for people who need them'..

Collapse
Posted by Dave Bauer on
I agree with Simon. The learning curve is very steep, but it doesn't have to be that way. I think the proposed developer docs will help this.  The design docs are so out of date, and were never fully implemented anyway. If we need design docs, they should be simplified and updated to reflect the current state of the code. But I think documentation for someone who wants to build a web site with OpenACS is more important. Documentation for someone who wants to take existing packages and build a site as well as for someone who needs to build a new package is the most important.
I like the way that the PostgreSQL group have done their docs. Five 'books', each aimed at a target audience - really nice, and very easy to find what you need in.
I totally agree with Simon, too. I could consider myself as a part of the techies with less experience group. I have a working system, I've read through the installation instructions and most of the developer's guide etc. But as a person who would like to build a site with the existing tools (and not yet quite ready to build own packages) I find the documentation ending too soon.

From my point of view, the next thing to do after installation is not to develop new applications, but to use the existing, and that is where I find the current documentation lacking.

Of course you learn by doing, but I think there should be some docs to help that process.

Hi,

Reretably I have been busy with several things and only now got a chance to browse at this thread.

As some of you know (althought it doesn't show here) I am writing a course that will be used here at Univ. of Sydney. It is still quite immature but it is getting there.

The course is not designed for end users, but it will contain a number of demos for some of the applications.

The course is designed for undergrad students in e-commerce, they have courses in business and courses in software engineering. This one in particular will be called something like "Web application frameworks", and of course the tutorial/labs use OACS.

I expect that someone who finishes the course successfully will be able to use OACS as a webmaster, and will have an idea of the underlying issues, just enough to modify a package.

I will update the page were the content is in the next week or so, and would appreciate feedback.

cheers

Playing devil's advocate here...

It seems to me that if our packages had better UI design, it would be a lot easiser for newbies to figure out how to use them. I've always felt that if one has to break out the docs to figure out how to use a package at a basic level, then the software designer has failed.

In an ideal world I think one would need

  • High-level user docs - mostly a description of what it does (not how it does it) and any tricky bits
  • Developer docs which describe how to implement customizations (for the novice developer)
  • Well-documented code
Obviously we're not there yet, but if others feel similarly then we might want to expand this effort into a UI cleanup as well. IMHO it's a waste of time documenting how to use a bad UI.