Properly edited OFBiz manuals

[Torsten Schlabach-2]

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

[David E Jones-2]

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

[Jacopo Cappellato]

David E Jones wrote:

>
> ...
> 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).
>

Are we sure this is the best way to go? My fear is that no one will ever
maintain these releases (submitting patches for them etc.).
A slightly different approach could be this:

1) we issue releases regularly and very often, let's say once every two
months
2) each release will not undergo a full QA pass, however we will try to
issue it when the code is pretty stable (e.g. not immediately after a
big refactoring)
3) every time we do changes in the trunk that could cause backward
compatibility issues (changes to the existing data model, seed data,
jars etc...), we document them somewhere and if possible we provide
upgrade scripts or instructions (in order to upgrade from the latest
release only); when a release is done, these instructions are delivered
with it ("Upgrade notes from release X to new release X+1").

I think this approach (with its pros and cons) is easier to maintain by
the OFBiz community (because it's not so different from what we are
doing now) and could be acceptable by the OFBiz's users (because it's
similar to what most users are doing now, i.e. staying up-to-date with
the trunk to minimize upgrade costs).

Jacopo

[David E Jones-2]

On Dec 28, 2006, at 12:57 AM, Jacopo Cappellato wrote:

> David E Jones wrote:
>> ...
>> 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).
>
> Are we sure this is the best way to go? My fear is that no one will  
> ever maintain these releases (submitting patches for them etc.).
> A slightly different approach could be this:
>
> 1) we issue releases regularly and very often, let's say once every  
> two months
> 2) each release will not undergo a full QA pass, however we will  
> try to issue it when the code is pretty stable (e.g. not  
> immediately after a big refactoring)
> 3) every time we do changes in the trunk that could cause backward  
> compatibility issues (changes to the existing data model, seed  
> data, jars etc...), we document them somewhere and if possible we  
> provide upgrade scripts or instructions (in order to upgrade from  
> the latest release only); when a release is done, these  
> instructions are delivered with it ("Upgrade notes from release X  
> to new release X+1").
>
> I think this approach (with its pros and cons) is easier to  
> maintain by the OFBiz community (because it's not so different from  
> what we are doing now) and could be acceptable by the OFBiz's users  
> (because it's similar to what most users are doing now, i.e.  
> staying up-to-date with the trunk to minimize upgrade costs).

I guess it depends on what the goal of doing a release is. In my mind  
the goal should be to create (over time...) a stable set of artifacts  
that people can build and deploy on if they choose not to go with the  
latest/greatest.

What you're describing is interesting, but how is that any different  
than just using the latest from SVN with a little timing based on  
knowing what is going on added in, and keeping a list somewhere of  
all non-backwards compatible changes and their revision numbers?

On that last bit, whatever we do with the releases having an official  
wiki page with all non-backward-compatible changes listed on it with  
the revision number for each would be a good thing to do...

But, back to the main point: what is the goal of a release in your  
mind (and in the mind of anyone else reading in too)?

-David

[Torsten Schlabach-2]

Hi David (and others),

 > But, back to the main point: what is the goal of a release in your
 > mind (and in the mind of anyone else reading in too)?

To have a reproduceable and tested state of code. I would like to take
the perspective of a business end-user here once again. If I was running
my company on OFBiz (we plan to do so, by the way) I would want to make
sure that a release contains code that has been properly tested. So if I
run 1.0 now and I get the chance to upgrade to 1.1, I would expect that
there is no broken functionality because I have real people doing their
daily work using that software and also our customers would not be too
happy if they receive wrong invoices because some developer felt like
checking in some untested changes to invoice generation and I just had
the bad luck to update to the SVN version which had that in.

Also a release is about support. Put yourself in the shoes of someone
making a living of implementing and supporting several customers that
run their individual OFBiz installations. How are you ever going to
compare behaviour, against what would you ever file a bug, how would the
customer ever be able to tell what version he's running if there are no
releases?

What I could imaging and would like to suggest though:

Have you thought about not having releases of the whole package at a
time, but releasing components. You could version the framework, the
"execution environment" so to say and then version the indidual modules
(Marketing, Partners, ...). That would allow for a user to upgrade what
he needs to upgrade. You should still use some Linux package
maintainance system as a guide how to manage compatibility, basically
how to do SCM in the original sense of the word.

So I could find out, that in my installation I am running:

OFBiz Base:       1.0.12
OFBiz CRM:        1.1.3
OFBiz Accounting: 1.0.0

Now the team which is maintaining the accounting module feels like
releasing version 1.1.0 which still requires OFBiz Base 1.0.5 or higher.
I have 1.0.12, so I should be ok.

Next month, you might have a release of CRM which is 2.0.1 because is
has made a major leap forward in functionality. For that to happen, you
had to update the Base framework as well. So CRM 2.0.1 requires at least
OFBiz Base 1.1.0. Get the idea?

IMO the key to success of OFBiz will be to make sure you have enough
sub-communities which are going to focus on vertical functionality as
well as on locales. But keep them on apache.org and by all means avoid a
situation where a "basic OFBiz" is real OSS but to really use it in a
business, you need the X, Y and Z components which are 300 USD, 2500 USD
and 400 USD per seat and only work with an outdated version of the
package itself. Or even worse: You are not going to find any compatible
versions of X, Y and Z at all to even get them installed.

This kind of threading and pseudo-commercialization was and is a massive
road-block to the success of something like Compiere and IMO OFBiz
biggest opportunity is to just do better here.

Regards,
Torsten


David E Jones schrieb:

>
> On Dec 28, 2006, at 12:57 AM, Jacopo Cappellato wrote:
>
>> David E Jones wrote:
>>
>>> ...
>>> 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).
>>
>>
>> Are we sure this is the best way to go? My fear is that no one will  
>> ever maintain these releases (submitting patches for them etc.).
>> A slightly different approach could be this:
>>
>> 1) we issue releases regularly and very often, let's say once every  
>> two months
>> 2) each release will not undergo a full QA pass, however we will  try
>> to issue it when the code is pretty stable (e.g. not  immediately
>> after a big refactoring)
>> 3) every time we do changes in the trunk that could cause backward  
>> compatibility issues (changes to the existing data model, seed  data,
>> jars etc...), we document them somewhere and if possible we  provide
>> upgrade scripts or instructions (in order to upgrade from  the latest
>> release only); when a release is done, these  instructions are
>> delivered with it ("Upgrade notes from release X  to new release X+1").
>>
>> I think this approach (with its pros and cons) is easier to  maintain
>> by the OFBiz community (because it's not so different from  what we
>> are doing now) and could be acceptable by the OFBiz's users  (because
>> it's similar to what most users are doing now, i.e.  staying
>> up-to-date with the trunk to minimize upgrade costs).
>
>
> I guess it depends on what the goal of doing a release is. In my mind  
> the goal should be to create (over time...) a stable set of artifacts  
> that people can build and deploy on if they choose not to go with the  
> latest/greatest.
>
> What you're describing is interesting, but how is that any different  
> than just using the latest from SVN with a little timing based on  
> knowing what is going on added in, and keeping a list somewhere of  all
> non-backwards compatible changes and their revision numbers?
>
> On that last bit, whatever we do with the releases having an official  
> wiki page with all non-backward-compatible changes listed on it with  
> the revision number for each would be a good thing to do...
>
> But, back to the main point: what is the goal of a release in your  mind
> (and in the mind of anyone else reading in too)?
>
> -David
>

[Jacopo Cappellato]

David E Jones wrote:

>
> I guess it depends on what the goal of doing a release is. In my mind
> the goal should be to create (over time...) a stable set of artifacts
> that people can build and deploy on if they choose not to go with the
> latest/greatest.
>
> What you're describing is interesting, but how is that any different
> than just using the latest from SVN with a little timing based on
> knowing what is going on added in, and keeping a list somewhere of all
> non-backwards compatible changes and their revision numbers?
>

Yes, you have described pretty well what I'm suggesting; I'd only add to
these that we should also create the upgrade services (and/or upgrade
instructions) every time we commit a non-backwards compatible change in
svn. As you said, this is not so different from what we are (implicitly)
suggesting to do right now (as a best practice to stay up-to-date with
the trunk) but I think that it would be nice if the community will
officially support it for a few reasons:

1) it's often difficult for users to pick a 'stable' svn snapshot
2) it's often difficult for users to keep track of important changes
between their revision and the trunk
3) since it is not so different from what we are suggesting right now,
it will not add a huge cost maintaining these extra processes/releases

> On that last bit, whatever we do with the releases having an official
> wiki page with all non-backward-compatible changes listed on it with the
> revision number for each would be a good thing to do...
>

+1

> But, back to the main point: what is the goal of a release in your mind
> (and in the mind of anyone else reading in too)?
>

I'd like to get the opinions from others too.
Personally I think that releases (or release instructions/plans) should
at least help users to keep their system/data in sync with the main
trunk, minimizing the upgrade costs and simplifying the users' decisions
(i.e. "should I upgrade now?").
Of course it would also be great to have a real 'stable' releases (with
patches for them etc...) as you are suggesting (and I really think we
could implement the two approaches simultaneously since what I've
proposed could be the basis of a real release management) but I'm not
sure the community will really maintain them...

Jacopo

> -David
>

[Scott Gray]

Hi Jacopo, David

I would just as happily submit patches for releases as I do for the
trunk, and perhaps we should just assume the community can handle it
until we are proven otherwise?  I would expect that we could handle the
first release easily, and it would just get harder as the number of
releases increases?

Regards
Scott

Jacopo Cappellato wrote:
> Of course it would also be great to have a real 'stable' releases
> (with patches for them etc...) as you are suggesting (and I really
> think we could implement the two approaches simultaneously since what
> I've proposed could be the basis of a real release management) but I'm
> not sure the community will really maintain them...

[Torsten Schlabach-2]

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

[Jacopo Cappellato]

Hi Torsten,

I will focus my attention to the second part of your post, where you
describe your ideas for an OFBiz manual(s).
What you say is interesting and it's probably worth of a try.

My only concern is that OFBiz is an ERP system, and it can handle very
complex and diverse scenarios (such as industry specific processes
etc...) if properly configured and set up.
However the process of capturing the specific needs of a company and
then mapping them to the existing OFBiz features and finally configuring
the system and the data to work well with these processes (and possibly
customize the system) is always a challenge and no manual, in my opinion
can be written for them. Not because OFBiz is complex, but because the
processes it can handle are complex and diverse.
This is the reason because you'll find plenty of manuals about, let's
say, MS Access and very few ones (if any) about SAP.

I usually think of OFBiz as a calculator; you can write a good manual
for it, and this is a good thing to have; however with it only, if you
don't have a solid mathematic knowledge, you will never resolve a
complex mathematical problem.

In the past I've often seen persons looking for a good and free OFBiz
manual, but often their real need was for a solution to their specific
needs (the mathematical problem) and not only information about the tool.

Jacopo

Torsten Schlabach wrote:

> 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

[Torsten Schlabach-2]

Hi Jacopo,

 > This is the reason because you'll find plenty of manuals about, let's
 > say, MS Access and very few ones (if any) about SAP.

Sure?

Try

http://www.amazon.com/s/ref=nb_ss_gw/104-4369286-1593533?url=search-alias%3Daps&field-keywords=SAP&Go.x=11&Go.y=15&Go=Go

But I hear what you're saying. ERP is a complex beast, no doubt. But if
people fail with the basics, which is to me:

- Installing the software
- Creating user accounts for the people working in the company
- Creating financial accounts
- Start capturing prospects and customers
- Records sales, printing invoices and doing accouts receivable

you will never arrive at what you're talking about.

I mean, let's face it: Most of us are not just enthusiasts who love to
play with code but need to make a living out of that. That means, many
of us are looking at paid consulting, training, implementation and maybe
even development work around OFBiz. Which is fine. No problem.

But the market of people who might want to buy these services grows with
the number of basic, plain installations (what the guy's from Walldorf,
German call "Base") of OFBiz which are in use. You can only sell
consultancy for Linux because millions of people found Linux useful and
started using it and then maybe discovered that they need help with
something very specific, so they tried to find that and were willing to
pay for it, but if they had not been convinced about Linux in the first
place, they might have spent their money on a license for MacOS or
Windows. No matter if that would have solved their problem, they would
no longer be your potential customers. They'd be lost for you as a
source of revenue.

My point is to lower the entry barrier to OFBiz. It is already low
because it's OSS, that's good. But what's wrong if people chosse to use
it maybe only as customer database or only as an accounting system in
the first place, just because they need one, it's there and it's
available now and without prohibitive advance payment. As they discover
they like it, they will probably want to start and migrate their
existing legacy (your name it) app to OFBiz. But they will add to the
user's community and contribute to a strong user base.

Today, at Universities around the world, when you learn what an
operating system is, you use Linux. When you learn what a webserver is,
you use Apache httpd. When you learn what XML, XSLT and the like is all
about, you use Apache Cocoon. When you learn what a J2EE container is
all about, you're likely to use either JBoss or Geronimo. When you learn
what an ERP system is, and you're studying at a western university that
either has enough money or is considered important enough, you will use SAP.

What do you think where's the problem in that chain of thought?

Regards,
Torsten


Jacopo Cappellato schrieb:

> Hi Torsten,
>
> I will focus my attention to the second part of your post, where you
> describe your ideas for an OFBiz manual(s).
> What you say is interesting and it's probably worth of a try.
>
> My only concern is that OFBiz is an ERP system, and it can handle very
> complex and diverse scenarios (such as industry specific processes
> etc...) if properly configured and set up.
> However the process of capturing the specific needs of a company and
> then mapping them to the existing OFBiz features and finally configuring
> the system and the data to work well with these processes (and possibly
> customize the system) is always a challenge and no manual, in my opinion
> can be written for them. Not because OFBiz is complex, but because the
> processes it can handle are complex and diverse.
> This is the reason because you'll find plenty of manuals about, let's
> say, MS Access and very few ones (if any) about SAP.
>
> I usually think of OFBiz as a calculator; you can write a good manual
> for it, and this is a good thing to have; however with it only, if you
> don't have a solid mathematic knowledge, you will never resolve a
> complex mathematical problem.
>
> In the past I've often seen persons looking for a good and free OFBiz
> manual, but often their real need was for a solution to their specific
> needs (the mathematical problem) and not only information about the tool.
>
> Jacopo
>
> Torsten Schlabach wrote:
>
>> 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

[Jacopo Cappellato]

Hi Torsten,

please see my comments inline:

Torsten Schlabach wrote:

> Hi Jacopo,
>
>  > This is the reason because you'll find plenty of manuals about, let's
>  > say, MS Access and very few ones (if any) about SAP.
>
> Sure?
>
> Try
>
> http://www.amazon.com/s/ref=nb_ss_gw/104-4369286-1593533?url=search-alias%3Daps&field-keywords=SAP&Go.x=11&Go.y=15&Go=Go 
>
>

yeah... you are right, a lot of them indeed!

> But I hear what you're saying. ERP is a complex beast, no doubt.

yes, this is what I meant... in order to implement an ERP system you
need a lot of background knowledge/study.

> But if
> people fail with the basics, which is to me:
>
> - Installing the software
> - Creating user accounts for the people working in the company
> - Creating financial accounts
> - Start capturing prospects and customers
> - Records sales, printing invoices and doing accouts receivable
>
> you will never arrive at what you're talking about.
>

I agree with you about the idea of providing a manual with basic
concepts to start with.
However the 'fundamental' features needed are very diverse and
subjective and I'm pretty sure that many of my customers, if asked to
write down such a list, would start with a totally different set of
features from the one you have provided above.

By the way, I'd really love to see better open source manuals about
OFBiz since I totally believe in the OSS model, I just wanted to share
my past experiences about (some) users expectations about documentation
and ERP systems.

Jacopo

[davidnwelton]

> > But if
> > people fail with the basics, which is to me:
> >
> > - Installing the software
> > - Creating user accounts for the people working in the company
> > - Creating financial accounts
> > - Start capturing prospects and customers
> > - Records sales, printing invoices and doing accouts receivable
> >
> > you will never arrive at what you're talking about.
> >
>
> I agree with you about the idea of providing a manual with basic
> concepts to start with.
> However the 'fundamental' features needed are very diverse and
> subjective and I'm pretty sure that many of my customers, if asked to
> write down such a list, would start with a totally different set of
> features from the one you have provided above

So, perhaps the best thing is to get people collaborating on what is
important to them, and they are willing to contribute to.  Torsten, do
you think you could write some basic documentation about getting
started with those features you list above?  Even if it's not much
more than bullet points?

--
David N. Welton
 - http://www.dedasys.com/davidw/

Linux, Open Source Consulting
 - http://www.dedasys.com/

[Torsten Schlabach-2]

 > Torsten, do
 > you think you could write some basic documentation about getting
 > started with those features you list above?  Even if it's not much
 > more than bullet points?

Sure. I would use the help of the people that I currently help setting
this up.

Though I should somehow integrate this with and have the outcome replace

http://ofbizwiki.go-integral.com/Wiki.jsp?page=OnlineUserManual
http://docs.ofbiz.org/display/OFBIZ/Application+Reference+for+Users
and / or
http://incubator.apache.org/ofbiz/docs/GettingAndUsingOFBiz.pdf
http://docs.ofbiz.org/display/OFBTECH/OFBiz+Basic+Production+Setup+Guide

(See what I mean when I wrote about the ONE place?)

I am willing to walk the talk, but I'd ask from some buyin to the
original idea of proper manuals, editing in co-operation with a
publisher. I am not sure who would have to authorized this. Probably
nobody would be able to forbid me talking to a publisher about doing
something like that and making it an Open Book.

But the publisher will be asking if the PMC at least agrees and supports
this and wants this to happen.

Any by the way:

No matter in what industry you are.
No matter if your focus is eCommerce or if you're running a shop or a
consultancy business,
the basics remain the same.

Every serious user of an ERP system needs to record addresses of
customers and suppliers.
Every serious user of an ERP system will want to customize the
templateds for any documents that go to customers, i.e. include their
logo, use localized address formats, etc.
Every business needs at least basic financial accounting.
Every business needs to be able to create users and have them login. Or
who's seriously using admin/ofbiz to record real live business. Or had
set up the system in a way that any intern in the company can export the
whole customer database and the financial accounts and take them home?

Regards,
Torsten

David Welton schrieb:

>> > But if
>> > people fail with the basics, which is to me:
>> >
>> > - Installing the software
>> > - Creating user accounts for the people working in the company
>> > - Creating financial accounts
>> > - Start capturing prospects and customers
>> > - Records sales, printing invoices and doing accouts receivable
>> >
>> > you will never arrive at what you're talking about.
>> >
>>
>> I agree with you about the idea of providing a manual with basic
>> concepts to start with.
>> However the 'fundamental' features needed are very diverse and
>> subjective and I'm pretty sure that many of my customers, if asked to
>> write down such a list, would start with a totally different set of
>> features from the one you have provided above
>
>
> So, perhaps the best thing is to get people collaborating on what is
> important to them, and they are willing to contribute to.  Torsten, do
> you think you could write some basic documentation about getting
> started with those features you list above?  Even if it's not much
> more than bullet points?
>

[Jacopo Cappellato]

Torsten Schlabach wrote:

>
> Though I should somehow integrate this with and have the outcome replace
>
> http://ofbizwiki.go-integral.com/Wiki.jsp?page=OnlineUserManual
> http://docs.ofbiz.org/display/OFBIZ/Application+Reference+for+Users
> and / or
> http://incubator.apache.org/ofbiz/docs/GettingAndUsingOFBiz.pdf
> http://docs.ofbiz.org/display/OFBTECH/OFBiz+Basic+Production+Setup+Guide
>
> (See what I mean when I wrote about the ONE place?)
>

Yes, there is indeed a lot to do in this direction (integrating/unifying
information).

> I am willing to walk the talk, but I'd ask from some buyin to the
> original idea of proper manuals, editing in co-operation with a
> publisher. I am not sure who would have to authorized this. Probably
> nobody would be able to forbid me talking to a publisher about doing
> something like that and making it an Open Book.
>
> But the publisher will be asking if the PMC at least agrees and supports
> this and wants this to happen.
>

I would be in favor, no problems for me.

> Any by the way:
>
> No matter in what industry you are.
> No matter if your focus is eCommerce or if you're running a shop or a
> consultancy business,
> the basics remain the same.
>
> Every serious user of an ERP system needs to record addresses of
> customers and suppliers.
> Every serious user of an ERP system will want to customize the
> templateds for any documents that go to customers, i.e. include their
> logo, use localized address formats, etc.
> Every business needs at least basic financial accounting.
> Every business needs to be able to create users and have them login. Or
> who's seriously using admin/ofbiz to record real live business. Or had
> set up the system in a way that any intern in the company can export the
> whole customer database and the financial accounts and take them home?
>

Any serious user of an ERP system will need *much* more than this :-)

Jacopo

> Regards,
> Torsten
>
> David Welton schrieb:
>>> > But if
>>> > people fail with the basics, which is to me:
>>> >
>>> > - Installing the software
>>> > - Creating user accounts for the people working in the company
>>> > - Creating financial accounts
>>> > - Start capturing prospects and customers
>>> > - Records sales, printing invoices and doing accouts receivable
>>> >
>>> > you will never arrive at what you're talking about.
>>> >
>>>
>>> I agree with you about the idea of providing a manual with basic
>>> concepts to start with.
>>> However the 'fundamental' features needed are very diverse and
>>> subjective and I'm pretty sure that many of my customers, if asked to
>>> write down such a list, would start with a totally different set of
>>> features from the one you have provided above
>>
>>
>> So, perhaps the best thing is to get people collaborating on what is
>> important to them, and they are willing to contribute to.  Torsten, do
>> you think you could write some basic documentation about getting
>> started with those features you list above?  Even if it's not much
>> more than bullet points?
>>

[davidnwelton]

> Any serious user of an ERP system will need *much* more than this :-)

Certainly, but you have to start somewhere, and it helps to not look
at the whole, enormous task, but rather some achievable bits and
pieces that can be accomplished soonish.

--
David N. Welton
 - http://www.dedasys.com/davidw/

Linux, Open Source Consulting
 - http://www.dedasys.com/

[Jacques Le Roux]

From: "Torsten Schlabach" <[hidden email]>

> 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.

I totally agree with this POV and believe that we must clear from everywhere old, false and deprecated informations.
But this cost time (or money if you want) and I look forward to any efforts in in this direction.

However I will create a Jira issue to point some places where such old, false and deprecated informations may be found.
For a beginning I will use yours ;o)

http://ofbizwiki.go-integral.com/Wiki.jsp?page=OnlineUserManual
http://docs.ofbiz.org/display/OFBIZ/Application+Reference+for+Users
and / or
http://incubator.apache.org/ofbiz/docs/GettingAndUsingOFBiz.pdf
http://docs.ofbiz.org/display/OFBTECH/OFBiz+Basic+Production+Setup+Guide

I do not comment more the other (very interesting) part of this mail (and sequels) because I'm not a PMC member.
But if I was one I think my 1st reflex should be to think about how to organize such a work... and I'm absolutly confident on PMC
members for this :o)

Thanks

Jacques

[Jacques Le Roux]

From: "Jacopo Cappellato" <[hidden email]>
> Of course it would also be great to have a real 'stable' releases (with
> patches for them etc...) as you are suggesting (and I really think we
> could implement the two approaches simultaneously since what I've
> proposed could be the basis of a real release management) but I'm not
> sure the community will really maintain them...

Why not ? We may take the challenge...

Jacques

[Jacques Le Roux]

As annouced I created a Jira issue for this : http://issues.apache.org/jira/browse/OFBIZ-568

Thanks in advance to anyone who want to contribute

Jacques

----- Original Message -----
From: "Jacques Le Roux" <[hidden email]>
To: <[hidden email]>
Sent: Thursday, December 28, 2006 2:30 PM
Subject: Re: Properly edited OFBiz manuals

> From: "Torsten Schlabach" <[hidden email]>
> > 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.
>
> I totally agree with this POV and believe that we must clear from everywhere old, false and deprecated informations.
> But this cost time (or money if you want) and I look forward to any efforts in in this direction.
>
> However I will create a Jira issue to point some places where such old, false and deprecated informations may be found.
> For a beginning I will use yours ;o)
>
> http://ofbizwiki.go-integral.com/Wiki.jsp?page=OnlineUserManual
> http://docs.ofbiz.org/display/OFBIZ/Application+Reference+for+Users
> and / or
> http://incubator.apache.org/ofbiz/docs/GettingAndUsingOFBiz.pdf
> http://docs.ofbiz.org/display/OFBTECH/OFBiz+Basic+Production+Setup+Guide
>
> I do not comment more the other (very interesting) part of this mail (and sequels) because I'm not a PMC member.
> But if I was one I think my 1st reflex should be to think about how to organize such a work... and I'm absolutly confident on PMC
> members for this :o)
>
> Thanks
>
> Jacques

[David E Jones-2]

On Dec 28, 2006, at 2:06 AM, Torsten Schlabach wrote:

> Have you thought about not having releases of the whole package at  
> a time, but releasing components. You could version the framework,  
> the "execution environment" so to say and then version the indidual  
> modules (Marketing, Partners, ...). That would allow for a user to  
> upgrade what he needs to upgrade. You should still use some Linux  
> package maintainance system as a guide how to manage compatibility,  
> basically how to do SCM in the original sense of the word.
>
> So I could find out, that in my installation I am running:
>
> OFBiz Base:       1.0.12
> OFBiz CRM:        1.1.3
> OFBiz Accounting: 1.0.0
>
> Now the team which is maintaining the accounting module feels like  
> releasing version 1.1.0 which still requires OFBiz Base 1.0.5 or  
> higher. I have 1.0.12, so I should be ok.
>
> Next month, you might have a release of CRM which is 2.0.1 because  
> is has made a major leap forward in functionality. For that to  
> happen, you had to update the Base framework as well. So CRM 2.0.1  
> requires at least OFBiz Base 1.1.0. Get the idea?

This has been discussed a number of times and I am 100% against it at  
this point. If we had 100 developers and we were trying to figure out  
how to keep everything moving smoothly this might be okay, assuming  
about 10 of those 100 developers contributing on a regular basis were  
doing package management, then maybe.

Personally, the library management in Linux is one thing I HATE HATE  
HATE about it. It makes the system a nightmare and sometimes because  
there are system level libraries you have to do super-funky stuff to  
get 2 different programs that require different versions of non-
backward compatible libraries to run together...

We may very well start versioning the framework separately at some  
point in the future, and you can already run the framework without  
the applications (just delete the applications and specialpurpose  
directories). Totally separating them would mean moving the  
applications to somewhere else in SVN and including the built  
framework but not the code of the framework with the applications (in  
SVN anyway).

Splitting out each component to have a different version number: I'll  
fight that pretty hard because I think it would just waste a bunch of  
effort and eventually fail. I don't think it would bring down the  
project, but it would kill progress on various things for a while...

> IMO the key to success of OFBiz will be to make sure you have  
> enough sub-communities which are going to focus on vertical  
> functionality as well as on locales. But keep them on apache.org  
> and by all means avoid a situation where a "basic OFBiz" is real  
> OSS but to really use it in a business, you need the X, Y and Z  
> components which are 300 USD, 2500 USD and 400 USD per seat and  
> only work with an outdated version of the package itself. Or even  
> worse: You are not going to find any compatible versions of X, Y  
> and Z at all to even get them installed.
>
> This kind of threading and pseudo-commercialization was and is a  
> massive road-block to the success of something like Compiere and  
> IMO OFBiz biggest opportunity is to just do better here.

Unfortunately we can't do ANYTHING about what other people decide to  
build based on OFBiz and how they decide to distribute it. We aren't  
in the business of doing things in a GPL way, and we want to  
encourage commercial as well as open source derivative works. That is  
very explicit in the Apache 2.0 license and in how OFBiz has been run  
since the beginning.

Fortunately there aren't any forks of the base OFBiz code base, and I  
think that is partially because of this openness. There are a few  
derivatives where people have chosen to do them as open source (or  
semi-open source with a GPL/commercial dual license), and these to  
some extent do compete with functionality in OFBiz. That's their  
choice unfortunately and can make things more confusing for  
prospective users, but in general it's a healthy thing to build up  
more around OFBiz.

-David

[David E Jones-2]

On Dec 28, 2006, at 2:09 AM, Jacopo Cappellato wrote:

> David E Jones wrote:
>> I guess it depends on what the goal of doing a release is. In my  
>> mind the goal should be to create (over time...) a stable set of  
>> artifacts that people can build and deploy on if they choose not  
>> to go with the latest/greatest.
>> What you're describing is interesting, but how is that any  
>> different than just using the latest from SVN with a little timing  
>> based on knowing what is going on added in, and keeping a list  
>> somewhere of all non-backwards compatible changes and their  
>> revision numbers?
>
> Yes, you have described pretty well what I'm suggesting; I'd only  
> add to these that we should also create the upgrade services (and/
> or upgrade instructions) every time we commit a non-backwards  
> compatible change in svn. As you said, this is not so different  
> from what we are (implicitly) suggesting to do right now (as a best  
> practice to stay up-to-date with the trunk) but I think that it  
> would be nice if the community will officially support it for a few  
> reasons:
>
> 1) it's often difficult for users to pick a 'stable' svn snapshot
> 2) it's often difficult for users to keep track of important  
> changes between their revision and the trunk
> 3) since it is not so different from what we are suggesting right  
> now, it will not add a huge cost maintaining these extra processes/
> releases

The problem I see, trying to look at it from the point of a  
prospective end-user, is that this sort of frequent release doesn't  
help me a lot.

1. If I want a good, stable version where I don't have to worry about  
bugs, which one do I choose?

2. If I realize there is no perfect version because of constrained  
community resources but at least want to group together with others  
to support a certain release, which one do I choose when there are so  
many coming out so fast?

3. Once I have chosen and have been running for a while and want to  
upgrade OFBiz, which newer version do I choose (related to the above  
questions) and how much work is it going to be to not be able to  
update from that version to the version I choose, but instead go  
through the upgrade processes for every version between that one and  
the one I choose?

>> But, back to the main point: what is the goal of a release in your  
>> mind (and in the mind of anyone else reading in too)?
>
> I'd like to get the opinions from others too.
> Personally I think that releases (or release instructions/plans)  
> should at least help users to keep their system/data in sync with  
> the main trunk, minimizing the upgrade costs and simplifying the  
> users' decisions (i.e. "should I upgrade now?").
> Of course it would also be great to have a real 'stable' releases  
> (with patches for them etc...) as you are suggesting (and I really  
> think we could implement the two approaches simultaneously since  
> what I've proposed could be the basis of a real release management)  
> but I'm not sure the community will really maintain them...

I'd say if people want to stay in sync with the trunk, there is  
nothing better than the trunk for doing so... In my opinion doing  
some sort of regular "release" would only make it more difficult for  
people to keep up with the trunk and participate in or contribute to  
OFBiz because they would never be quite up to date.

What I'm hoping for is a single, infrequent branch that people can  
rally around and maintain together. If we only do one of these each  
year or so then there will never be a question about which one needs  
fixes back patched to it as we'd only support at MOST 2-3 of these at  
any given time. That would mean people would need to update at least  
once every 3 years, but of course that's just a random artificial  
number and being a community driven thing if there is a group that  
wants to continue to maintain an older branch then great, more power  
to them!

People looking for a good release to use if they are asking question  
#1 above would use the latest release in the latest stable branch  
that is at least, say, 3 months old. For people asking question #2  
above they could just use the latest stable branch as-is from the SVN  
directory for that branch and participate in making the branch better.

-David