Hi David,
on the original subject of this thread:
> The "official" place for this right now is the docs.ofbiz.org site.
Is that subject to change with graduation? Shouldn't it be somewhere at
ofbiz.apache.org or do you plan to just keep linking from
ofbiz.apache.org to docs.ofbiz.org?
Ok, I think this is not going to be the most important question EXCEPT
that my prior experience with stuff like that has shown that it is extra
important to have ONE place for stuff and have that place organized in a
way that someone who's visiting the site for the first time will have a
chance to grasp what's where, see the good stuff and not be irrated for
example by manuals which contain nothing but a table of contents of what
someone intended to write later, but which is several months old. So I
usually support taking a quite radical approach which is killing
everything except the offical place and - in case the official place is
a Wiki - have someone do some good Wiki gardening. That should be
someone or a team which is appointed by and their editorial decisions
supported by the PMC.
> In short, in order to produce reasonable documentation we need to
> pump up the contributor and user volume quite a bit...
Quite frankly, IMO, you mix up the chicken and the egg here. I believe
that good documentation is what you need to draw people (when I say
people, this includes companies, universities, real dedicated resources)
into the project and pump up the volume.
Let's do a little reality check here:
I have been walking around trying to get several people interested in
using OFBiz, as using is a prerequsite for helping to develop. Nobody is
going to spent time on contributing to something he or she does not want
to use. Now with some of the people I had a good argument in the first
place: It does not cost anything, so you can never loose by trying. But
this is a weak argument, especially as you're competing against that 99
USD shrink-wrapped packages for small business which are available
anywhere in the local markets. (Which is why 350 USD or 149 USD just for
documentation is prohibitive IMO.)
Don't even start the debate about functionality of those packages versus
OFBiz. People will just don't care if they have the choice to pay 99 USD
for a package WITH a manual or 350 USD for JUST the manual which is
going to explain to them how to built themselves as system. Maybe only
to find out they don't have the skills and resources needed. Ok, I
understand, you have had the same experience somehow.
I always understood OSS like this:
- Feel free to help youself and you don't have to pay anthing except
attention (i.e. invest your time)
- If you want to have it done for you, you can pay someone to do it for you
This is a like Linux. You can download a free distro yourself. Or you
can pay a fee to Red Hat or Novell/SuSE if you think you want someone
who might be supporting you. Or like MySQL. You can download the whole
package including ALL features and you can read the WHOLE manual only.
Just if you feel like you need someone you can take to court in case it
looses your data, purchase a license IF you want to.
I am helping an IT company in Afghanistan. To the guys working there, 50
USD for a book is 1/20 th of their monthly income. That's as if a book
would be 500 or 1000 USD for you. But they have free or cheap (even
cheap by their standards) Internet access there, so they lerned to
download stuff, read, learn and develop their skills by helping
themselves. And they get quite far over time. And this is only possible
through true OSS, not if OSS is abused as a showcase for commercial
software.
The situation is similar in South America, in the middle east (except
that places like UAE and their neighbors) including Iraq and large parts
of Asia and even some economies in eastern Europe. Huge potential
markets for OFBiz on one hand and a lot of potential human resources
which might be interested in becoming a part of the project,
contributing and benefiting from it.
Coming back to the question of what I would propose:
Editing proper manuals requires an editorial process and people who have
done that before. As I said, I have been authoring computer books and I
have worked as an editor as well. So I think on one hand I know what
this is about. But on the other hand, I know my time limits as I need to
make a living and I fully agree that there is hardly going to be any
living in this and there may never be.
Nevertheless, some publishers at least in Germany, but probably also
somewhere else have embraced the concept of Open Books. That means, they
publish traditional books which are edited, printed and sold through
online and offline bookstores for normal prices. But at the same time,
they offer the whole book for free reading and download on the Internet.
A very famous example, at least in Germany, is this here:
http://www.galileocomputing.de/openbook/javainsel5/
("Inhaltsverzeichnis" in the upper left corner means "table of
contents". Click in there to see that the WHOLE book is online, not just
some sample chapters.)
"Java ist auch eine Insel" (Java is the name of an island as well) has
emerged to become THE book for people who want to learn Java, and
believe it or not, they sell it for money though they want 50,00 EUR for
it, which is more than 60 USD. And they sell it because people google
for Java questions and after they hit pages from that book for the 3rd,
4th, 5th time they find out that this book might be worth the money. But
then still, the profit they make from that is just enough to cover the
editorial process, which is way more time consuming than for other books
because they really take it serious.
A more global and OSS related example of the same concept would be:
http://www.amazon.com/exec/obidos/ASIN/1932394885/hiberthejavao-20
which is a hard-copy of
http://www.hibernate.org/hib_docs/v3/reference/en/html/
I could continue with examples where the success of the project is
directly connected to a well organized documentation, such as:
* Typo 3 (http://typo3.org/documentation/document-library/)
* Spring Framework
(http://static.springframework.org/spring/docs/2.0.x/reference/index.html)
I could also spot a number of OSS project which have a quite sound
codebase but if you browse the archives or their user's mailing lists,
50% of all questions are: Help, I cannot make this work at all. Those
are the projects which did not really make it.
So what I would do (and again, volunteer to try and actively take care
of) would be to get real existing publisher interested in doing that
OFBiz manuals, maybe in three volumes as disucussed before. These people
would have editors they could throw at that which would probably
motivate writers to really write up some useful documentation. For
example, you will be able to get university teachers interested in
suggesting students to partcipate in such an effort especially if it
will lead to a real printed book with their names on, even if it will
have 10 or 15 names on it, and these are usually skilled, committed
people who have time. (Which is what you and me don't have.)
I would also volunteer to use some resources of our company to help such
an effort and I would volunteer to mentor such an effort. This would be
what my time permits.
Let me know what you think.
Anybody, please share your opinions if you think this would be a way to
make this happen without putting an extra burden on the people available
to the project right now.
Regards,
Torsten
David E Jones schrieb:
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
