Forum OpenACS Q&A: documentation

Collapse
Posted by Robert Taylor on
hello everyone.

recently I have had the pleasure of watching a new user pick up oacs and take it for a test drive on the #openacs channel on irc. (as have a good number of members there as well).

what i mean is that rarely is one afforded an opportunity to watch someone with skills, talent and knowledge of other frameworks dig in and work so hard while asking questions publicly, to expose the barriers to entry.

as an extension of some of the other discussions that have been had on the forums with respect to openacs and broadening it's appeal, it seems to me that the next big project that needs to be tackled after the release of oacs 5.2 would be cleaning up and updating the documentation.

i think this is more important than working on installers (although that comes a close second), more important than making the site look even nicer, more important than cleaning up the html so its easier to style oacs on site wide deployments.

clearly, the lack of documentation is a far greater barrier to entry than any other variable that i have considered about the project and in my very humble opinion it is one that i believe needs to be tackled very seriously.

i am not a programmer by nature, but tcl and the basics of oacs seem to show that even non programmers should be able to use oacs with relative ease (for the most part), however I know that just by watching the IRC conversation, that I will never be able to push through to the more advanced stuff without the documentation issue being addressed. too many other skills are required to reverse engineer the knowledge from the current codebase.

how can a non programmer like me help the documentation issue?

what if anything can be done to spur work on the documentation issue? this link: https://openacs.org/doc/current/docbook-primer.html seems to summarize this very same question, something that has been talked about many many time i'm certain.

what problems have previous efforts to do the same faced?

and yes, i am volunteering to help the documentation project. i am not a coder and as such i'm not certain what more i can do than help organize the push to get it done. one thing is clear, after the release of 5.2, this must be top priority because without documentation something as huge as oacs is very difficult to use regardless of how easy it is to install.

what do you guys think?

Collapse
2: Re: documentation (response to 1)
Posted by Robert Taylor on
i've posted a link on the wiki page, and created a section called Documentation Project, of all things.

It catalogues some of the ideas discussed thus far.

I'm hoping anything that can help us think about documentation issues further.

Collapse
3: Re: documentation (response to 1)
Posted by Robert Taylor on
woops, here is the link:

https://openacs.org/wiki/

Collapse
4: Re: documentation (response to 1)
Posted by Jade Rubick on
Robert:

Interesting.

I've gone through exactly the same experience, watching a newcomer to OpenACS learn it and become proficient with it.

My two cents is that there is nothing more important than getting the installer right. Our documentation is actually very good, I think.

Anyway, here's how to change the documentation:

https://openacs.org/faq/one-faq?faq_id=161579

Collapse
5: Re: documentation (response to 1)
Posted by Alex Kroman on
As the newcomer that Jade is probably talking about perhaps it's time that I introduced myself. My name is Alex and I recently took over Jade's old job. Before I started here I did not have any experience with OpenACS having spent the past few years in the PHP world and before that ColdFusion.

In my brief experience coming up to speed with OpenACS the hardest thing for me was getting the thing installed. It took a few hours and if that had been a typical weekend project I might have given up before I got to see how cool this system is. No one likes wrestling with an installation, it's like going to a concert where the band takes 2 hours to set up their equipment, all you want to do is hear the rock!

Collapse
6: Re: documentation (response to 1)
Posted by Robert Taylor on
agreed.

installation issues are being dealt with as we move forward. there are a few rpm installers, a windows installer, a debian dotlrn installer and i'm trying to find time to package up plane jane oacs for debian.

from there, perhaps metainstallers will be needed like the ones for lamp that install mysql, php, apache and autoconfig. i can do this easily for debia (will take quite a bit of time), perhaps that can be looked at down the line.

the instructions are excellent and detailed, however, recently when i had to learn to install oacs on debian, i found a couple of issues:

a) no big picture overview of whats going on. the instructions are really quite great and detailed, some intro for people moving over would be nice.

b) different platforms put things in different places. an overview should have some notes on this, perhaps we should add more platform specific notation throughout the instructions to make sure newbs don't haveto reverse engineer how the instructions relate to their platform.

these aren't things i consider show stoppers, those that want to can hack away at it and succeed. some polishing could be helpfull i think.

as well i would like to mention that this discussion is not proposing any majour changes at all - i would like a collaborative approach and approach that simply builds on what we have already.

as an xtension to this, I have teamed up with a member from the #oacs irc channel to start looking at this indepth. I don't know his real account here but introductions will be made later. thus far we have agreed that he takes the lead for this effort and I will back him up as much as I can simply because I am so inexperienced with oacs and he has been around it for a while.

the consensus so far is that there is no objection to the documentation work that needs to be done, people seem to have some will to do it, what is needed is someone to help organize and structure the documentation and then start building from there.

i'm excited about oacs, but if i don't help get the documenation in shape i have no hope of learning it profficiently, there are far too many details that are missing and require the developer to reverse engineer the knowledge as they progress.

thank you for the comments, any input will help and is greatly appreciated!!!

anyone else have anything to share? your own personal experiences? how did everyone here manage to learn oacs and what difficulties have you had to overcome.