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

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.