The "official" place for this right now is the docs.ofbiz.org site.
This is running on Confluence, a wiki-style system, with a public
area and various "restricted" areas that are meant to be controlled
by editors that have a certain level of commitment to helping
maintain the documentation.
My general thoughts on this: OFBiz is a large system and at the
moment this sort of documentation effort is way beyond the scope of
what the community can handle. I may be wrong, but even if I'm not
there is hope as the community is growing significantly and hopefully
once the ASF incubator graduation is all settled we'll be able to re-
group and get some motion going in a good direction on things like this.
Still, the first priority after graduation is to do a community
supported branch "release". Again given the size of OFBiz relative to
the size of the community, we don't have resources to do a full QA
pass before issuing a release, so the release process for OFBiz will
be centered around a community effort to maintain a branch that will
have bug fixes, but not new features, as anything would be maintained
with a priority of stability over progress (new features, etc).
As for the sustainability of a documentation effort and level of
resources: we recognized a couple of years ago that this was a
problem and decided to try a semi-commercial approach. This is where
the end-user documentation site from Undersun came from, and it now
exists as the PDFs attached to a page on the docs.ofbiz.org site. We
gave up after 2 years on the commercial approach because even with
document licensing and custom documentation efforts it wasn't even
half enough to cover the cost.
With the current training videos from Undersun there is a similar
problem. Selling these packages at $350 each I am projecting enough
volume to recover the cost in about 1 year, which is also about the
frequency at which the content should be updated (now the framework
is fairly stable... in previous years this wouldn't have done any
good at all...). This is even the case where I tried to spend minimal
time on it by doing the reference book and outlining and recording
only, and then I paid a writer $12 an hour to create the
transcription. Doing a single pass on this cost about $25k.
Subtracting administrative and production costs for the packages the
company makes about $200-250 per package sold at full price, and
actually about 60% of them have been sold at a discount to date, so
we need to sell over 100 packages to recover the cost.
In short, in order to produce reasonable documentation we need to
pump up the contributor and user volume quite a bit... To date there
isn't even a commercially viable model, except perhaps the somewhat
happy medium this framework only training material has reached, but
it's still rather risky with no guarantee of return, and only hope of
any profit after a full year of sales. That's not terrible for a
product, unless you consider the life span of the product is only
about a year... ;)
So, yeah, we need volunteers to help with the docs.ofbiz.org site in
a big big way. At this point I don't see any other way we can hope to
have reasonable docs available at any cost for end-users, system
administrators, etc. So far there have been a few volunteers, but
only limited effort actually put into the stuff. Of course, you can
see a full history of it there and who to give credit to for each
little bit...
-David
On Dec 27, 2006, at 5:10 AM, Torsten Schlabach wrote:
Hi all!
Maybe this is the time of the year (at least in the christian
world) where many people have time to give thought to general
subjects and make up plans for the new year.
I do plan to spent some of my time and effort on OFBiz in 2007.
Now what I have been asking myself is:
Is there any ongoing effort to provide a properly edited set of
manuals for OFBiz? What I mean is any effort to come up with a
properly edited manual, consistently edited and kept up to date,
which might even be published as a traditional book (either through
a publisher or via print on demand) or the like.
Given the nature of OFBiz, such a manual would probably have to
have several volumes, such as:
1. Technical Reference Manual
Covering the technical aspects of how to install, run and maintain
OFBiz. The target audience would be system administrators that
don't necessarily care about any content in OFBiz but would like to
understand what app / web containers they have to provide, how to
plug OFBiz into any SSO systems, what logfiles to watch, how to do
backup and restore, howto upgrade, ...
2. Customization and User's Guide / Evaluation Guide
This would be the manual for any super user kind of people. This
manual would assume that someone installed an instance of OFBiz for
you and you're the one who is supposed to make it work for the
company.
So this manual would cover subjects such as: Setting up reference
data, how to capture customers, how to record an order, how to
print an invoice, how to customize the invoice layout, how to ...
This would probably also be the book which people will use even
without an installation to make up their mind if OFBiz is for them
or not.
3. Developer's Guide
This would cover how to customize and extent the functionality of
OFBiz. Maybe this should have two major sections, which are
framework development (how to extend the frameworks) and business
oriented development (how to implement new use cases with the
framework).
I understand that some of that material is there somehwere on the
site, but due to the history of OFBiz, there are three or even more
places in the meanwhile where documentation is stored and
maintained (or not maintained, but still staying around).
Now that the new infrastructure gets setup after graduation from
the Incubator, maybe it's a good time to think about a
documentation subproject which will maintain a properly edited set
of manuals for OFBiz.
WDYT?
I found that indeed may very successful Open Source projects have
extremely good and properly organized documentation, for example
Hibernate or Type 3 to name just two of them.
I have some prior experience of how it doesn't work (I am a
committer in another Apache project, though I haven't done a lot
there recently) and I have been authoring computer books before.
My time is limited, so I cannot do this alone, but if the PMC of
the project feels like it's worth the effort, I would try and help
with getting this started.
Regards,
Torsten
