Forum OpenACS Q&A: Outline of 'Getting Started with openACS for Dummies' - guidance/suggestions please!

I started a thread about the need for idiot-proof configuration instructions to followup the 'Congratulations' screen. Feedback from that thread sounds like documentation for configuring a site (hosting, installing modules, setting up look/feel, customizing the index page) without doing any package development whatsoever would be useful for a large percentage of people who just want to give openACS a whirl and see if it suits their needs. I think there's enough built in functionality to satisfy the vast majority of potential adopters out there - just need to make it a bit more accessible. Lars started a similar thread about setting up 'out of the box' useability which will be a great addition - but, and correct me if I'm wrong, still won't address this problem.

Since I'm at that stage myself and have specific needs for a project (strata management and news/community site for my condo), I have no problem documenting everything while I'm doing it. Instead of just looking at the specific needs of my project, I'm going to aim more at a generic personal-ish web site and the modules that a typical user might want. Here's what I'm proposing - please pipe in and let me know what you think (especially where I put 'more?':

• A very dumbed down how-to on using cvs for maintaining your site. For a basic site - is this even necessary or does it make it far easier to upgrade, back up, move to more of a production system (I'm planning on moving my server to a colo if my project takes off), other reasons? It would be nice to have a guide to configuring a gui cvs client for this - any suggestions on a client?
• Resurrect problem set 0 and the emacs quick reference guides - I can't recall who made them - David something or other? from the bad old days of the boot camp. I have to check what Jade has on her docs page.
• Blasphemy - a quick guide to doing your dev work on a windows machine via ssh. Cygwin perhaps? Too bad Homesite doesn't have a tcl module, perhaps activeState Komodo? Why you ask? As much as I love Linux, I just can't get it configured to my liking as easily as Windows - and why bother if I don't have to? Really, my main complaint is that Suse just refuses to enable my mouse wheel and once you've used a mouse wheel, there's no going back. RedHat found my mouse wheel but I couldn't get my nic recognized. Mandrake wouldn't give me X on my built in graphics card. Slackware did it all but it's more bsd based and I gave up half way through the openACS install because file locations and services were so different. I anticipate this is a typical experience for a new-ish Linux user (hell, I've been toying with it since rh 5 - maybe I'm just too lazy) coming from windows so why not just let them stick with windows?
• Section on setting up your home-based server to serve up openACS - configuring aolServer and openACS for your ip, installing and configuring Shorewall firewall, minimizing security risks as much as possible (although Shorewall should pretty much do that for you), using zoneedit as a dyndns so the world can see your site, hooking up to an uptime service (there's still one on openacs.org isn't there?), more?
• How to set up user groups and hierarchies - I'm thinking initially admin, friends, family, work, public - more? I'm pretty new to this part but as i understand it, you'll need user groups set up before you can set permissions on modules?
• Adding users - although this looks pretty straightforward, just a csv upload. It looks like passwords can be set with single user additions but not in batches?
• Adding users to qmail - perhaps webmin is easiest for all the different linux configuration settings
• Quick step by step guide for installing modules, enabling them and mapping them to url's on the site - It's too far from obvious from the Congratulations screen. Is there a definitive list of useable modules and descriptions of what they do? Looking at the installation pages, the version numbers are all over the map. openACS is at v4.6.3 - is it just me or wouldn't it seem logical to number any current and up to date module 4.6.3? I'll be looking to figure out exactly what modules are currently production-ish ready for postgres (oracle is irrelevant for the average user). Overall, how is the documentation in each module for configuring it? Ideally, the doc for each module should contain all the sample sql and whatnot needed to put samplings on the index page (like the latest posts from bboards on openacs.org) - is this the case now?
  Here's the modules I'm thinking would be popular - did I miss any?:
  • lars blogger and subblogs - can it be automated that every new user get's a subblog?
  • events
  • forums
  • download and file storage (are these supposed to go together)
  • general comments
  • news
  • wimpy point
  • chat
  • faq
  • mp3 jukebox
  • photo album - or should it be photo album lite?
  • simple survey
  • robot detection
  • spam system
  • webmail
  • whatever happened to homepage as was seen on photo.net?
• Setting permissions on said modules + I'm sure there's more needed here but haven't gotten that far myself yet
• And the big one - customizing the index page to show bits and pieces of available modules. Do we have a repository of examples that could be shown like Joel's or Lars' home pages. I know the openacs.org index page is available in cvs but can it just be downloaded without learning the ins and outs of cvs? The templates documentation is a good start but doesn't give any useful examples of say, showing the latest posts in a box in the lower left corner.
• Customizing the master template(s) for look and feel

I think that would cover most of what's missing between the Congratulations page and the Developer Tutorial. I know there are a lot of questions in there that I could find answers to by digging through the documentation and doing bboard searches but that's partly the point - joe user is not going to want to do that and will get discourages. Consider me to be joe user while I'm making the documentation - I'll probably ask a bunch of lame questions that, given 10-15 minutes of searching, I could find somewhere on this site.

I'm thinking this would be best done by putting all of this in a tutorial with a before (the congratulations page) and an after page with all the modules in place and a generic customized index page where a user can dump in their own graphics. I'm figuring it would just be html based since I've never used docBook - is there a wysiwyg interface for it? Before jumping in, I'd love to get feedback from the community and especially know where I might be duplicating efforts. What does everyone think?

• A very dumbed down how-to on using cvs for maintaining your site. I think cvs is pays for itself very quickly, even for beginners. The benefits are: safety net for rolling back to working code, both while developing something and when doing big changes on a site; ability to recover old work that you didn't think you'd need again; makes it possible to upgrade modified sites back to the main code tree. What can we do to lower the bar for people to adopt cvs? More hands-on examples? Have a look at the cvs notes (and here) in the developer tutorial; maybe they can be the basis of the even-simpler version.
• any suggestions on a client? WinCVS seems to be adequate.
• A quick guide to doing your dev work on a windows machine via ssh. Cygwin perhaps? There's no real difference between using a windows desktop and a linux desktop for OpenACS development. In both cases, you have a shell (putty or cygwin/ssh or a commercial product) for emacs, another shell for tailing the log, a web browser pointing at the work in progress, a web browser pointing to the admin pages, and a web browser for api-doc. Anybody using Eclipse?
• It looks like passwords can be set with single user additions but not in batches? Is there a scenario where you would want to set passwords in bulk uploads? When would you have a list of email/name/password? If you didn't have password, would you want to manually create a bunch? (It wouldn't be hard to add bulk password upload, though, and it would be a good project for another neophyte; after all, I added bulk user import and it took a few hours and I'm no developer).
• Adding users to qmail Why do you want to add users to qmail?
• Quick step by step guide for installing modules, enabling them and mapping them to url's on the site With 4.6.3, this is pretty easy - Go to /acs-admin/apm/packages-install, Enable whatever you want, and follow the instructions to auto-mount it (oops, seems broken on my site. bah). Sounds like we need a link from the Congratulations screen.
• Ideally, the doc for each module should contain all the sample sql and whatnot needed to put samplings on the index page Instead of sql, I think each package should provide an includeable template that is dynamic and has a visible action (a link or a button), like lars-blogger does. For example, my home page has adp code like this:

  <include src="/packages/lars-blogger/www/blog" url="/blog" max_content_length="350" max_num_items="4">

  and

  <include src="/packages/ja-boxscore/www/score" limit="9" url="/boxscore/">
  

• And the big one - customizing the index page to show bits and pieces of available modules. Do we have a repository of examples that could be shown like Joel's or Lars' home pages. Clearly the default Congratulations page isn't helping people. People don't read or want to read it, and apparently would rather have a page that's the starting point for customization. Suggestions on what that page would look like? My home page is an HTML table in .adp with includes for the main packages I want to highlight. Lars, how did you code yours? Other opinions?
• I've never used docBook - is there a wysiwyg interface for it?Not as such. But emacs works well, and if you put a bit of effort into docbook you are quickly rewarded by all of the html autogeneration it does, especially when you change things and don't have to go make a bunch of fixes. Try the Docbook walkthrough - using the pre-built xml files and Makefile as a working starting point to modify, you should get results in 10 minutes.

Thanks for the feedback. In answer to your questions:

• How to lower the cvs bar - The install docs do a great job of walking one through the initial setup. The problem is what to do next for people that don't routinely use cvs (and some explanation of why/what happens when you do x). After following the installation and the cvs check in (or was it out?), what next? It's been awhile since using cvs for me and that was winCVS. As I recall, once checked out, whenever a change is made to a file, it's flagged as needing update - but wait... thinking back to the install docs, aren't the source and working files the same? If I'm doing dev work on the server, there should be a live version and a separate dev version, shouldn't there? Anyhow, just confusing myself more...
• What's Excite? And where does one find it? As for the cygwin/emacs setup being same on unix/windows - very true. After working with emacs on the psets a few years back, I was pretty comfortable but is there a Windows alternative that works with standard windows key shortcuts and understands tcl syntax? I think Komodo does but it's not free and I haven't played with it myself.
• Setting passwords in batches/Qmail users - That's mostly for my needs. I want to get a list of all strata property owners from the council and assign both an email and password to each. These would be distributed ensuring at least an initial level of verifying user identities for voting purposes. I'd guess it's a 10 minute hack to add an additional column to the batch user upload
• Need a link from Congrats to package installation - that would be a start. I'm pretty well versed with installing and configuring apps but it took me a very long time to figure out what to do. On top of that, the package list gives no indication what each module really is or what to do with them. A basic walkthrough example for say lars blogger or some such would go a long way to enabling new users.
• Includeable template for each package - that would be great! I had no idea that blogger already does but I haven't started digging in yet either. I'm sure I'll be asking about more details on this later...
• default Congratulations page isn't helping people - I read it. I read it again. I followed the links. I decided this was going to take some effort to figure out... A starting point for customization of the look/feel would be great. A step by step to get from Congrats to a page like yours or Lars' would go a long way to getting new users educated on how
• Docbook walkthrough - I'll start toying with it. Expect questions...

So far, no mention of obvious duplication of effort. Guess I'll start plugging away this week! I owe my initial entry into the tech field to Philip's book and the ArsDigita homestudy on the psets - it will be nice to give something back.

Some initial links I've tracked down (most have been posted in the forums before - perhaps some could be added to the resources page):

• The emacs cheat sheet and 'getting ready for aD bootcamp' pages http://rgrjr.dyndns.org/emacs/study.html - emacs cheat sheet is at http://rgrjr.dyndns.org/emacs/emacs_cheat.html
• Archive of all the aD stuff - http://eveander.com/arsdigita/, I was specifically looking for the cvs article http://eveander.com/arsdigita/asj/version-control/ which has the great starter cvs link http://www.loria.fr/~molli/cvs/doc/cvs_toc.html referenced
• more to come, I'm sure

I started looking at docBooks as suggested by Joel - interestingly just as I was concluding that there was no way I was going to bother with the hassle of instaling, configuring, learning, taking 2-3x as long to type... Joel himself started a thread questioning whether docBooks is a barrier to creating documentation.

As I was searching through the bboards trying to find cvs and emacs answers, I came across quite a few 'newbie' documentation threads. Seems this project has been started numerous times before. Are the fruits of any of their labours available anywhere? The most promising thread proposed (and started but seemed to stop after a short time) adding a bunch of FAQ's to the openACS FAQ page. I think that's a great idea! If I set up my docs that way post them on the bboard for review/feedback, who do I have to talk to to get them added to the FAQ's?

And the best cvs introduction I've been able to find:

• http://www.andamooka.org/reader.pl?pgid=cvsbookmain_2&clid=387&nav=Table+of+Contents

I think this will be the starting point for coming up with a good 'cheat sheet' for what to do next with the cvs setup section of the installation guide. I'm thinking the setup should be the repository as the live server www.server.com on port 80 and the checked out working copy at dev.server.com on port 8000. Does that make sense? And any suggestions on the best way to keep the working copy of the db up to date? Can that be done via cvs as well or does a cron job script for dumping and updating the working copy already exist?