An observation on Getting Started documentation

[David Goodenough]

I notice that the documentation for getting started has recently been split
in two, one technical the other business.  This is excellent and makes it
much easier to read.

Reading the Business Setup document I am struck by the way in which it is
assumed that the only way to get started is to take the default seed data
and modify it, no-where does it describe how to start from scratch.  

When this is coupled with the discussion about who OfBiz is aiming at,
and which bits of what is a very extensive offering are regarded as basic
this has the effect that you end up disabling bits that you do not want
rather than enabling the bit that you want.  This also means that there
are things that are configured but about which you (the user) know nothing
and for which you have no use.

Is the subtext that defining from scratch is so complicated that it should
never be attempted.  If so perhaps this should be stated.

Of 15 pages (when I printed the document) basic company setup talks about
how to set up the basic business and occupies just one page, and then about
10 page cover the ecommerce aspects.  Tax is only mentioned as an adjunct of
the ecommerce section, and the setup of the accounting section is not even
mentioned.

There is also no mention of localisation.  Getting OfBiz to default to other
than the Dollar and American style Sales tax (and I am aware of the recent
discussion on VAT on this list) is not mentioned, and worse, it is not
mentioned that what is being described is a US model.

Perhaps a further subdivision is needed.  The basic company setup in one
document, accounting and localisation issues in a set of documents
identified by country (or groups of countries where they do things
sufficiently similarly), and then separate documents for the other bits
like ecommerce, manufacturing and warehousing.

Breaking the documentation up like this may also make it easier to get
contributions as the task is less daunting.

Just a thought.

David

[Jacques Le Roux]

David, all,

----- Original Message -----
> I notice that the documentation for getting started has recently been split
> in two, one technical the other business.  This is excellent and makes it
> much easier to read.

Yes I agree this is a very important point. I would say rather splitting between functionnal and technical concepts (in France we
would say also "Organic" for the later part because it's only deals with structures and not functions) . But that's only words...

> Reading the Business Setup document I am struck by the way in which it is
> assumed that the only way to get started is to take the default seed data
> and modify it, no-where does it describe how to start from scratch.

Yes that's true, but at least there is something to help you, remember it's open source, you may help (acts, acts, acts, ...;o) here
of course...

> When this is coupled with the discussion about who OfBiz is aiming at,
> and which bits of what is a very extensive offering are regarded as basic
> this has the effect that you end up disabling bits that you do not want
> rather than enabling the bit that you want.  This also means that there
> are things that are configured but about which you (the user) know nothing
> and for which you have no use.
>
> Is the subtext that defining from scratch is so complicated that it should
> never be attempted.  If so perhaps this should be stated.

Easy way, but why not !

> Of 15 pages (when I printed the document) basic company setup talks about
> how to set up the basic business and occupies just one page, and then about
> 10 page cover the ecommerce aspects.  Tax is only mentioned as an adjunct of
> the ecommerce section, and the setup of the accounting section is not even
> mentioned.

About tax it's even worse : it's obsolete ! Please search for Tax Authotiries in Nabble to know more...

> There is also no mention of localisation.  Getting OfBiz to default to other
> than the Dollar and American style Sales tax (and I am aware of the recent
> discussion on VAT on this list) is not mentioned, and worse, it is not
> mentioned that what is being described is a US model.

Yes that was already raised by Chris Howe here :
http://www.nabble.com/-jira--Created%3A-%28OFBIZ-149%29-Better-describe-complex-party-relationships-tf2082963.html#a5772036
And I believe also that something is missing in the data model to be able to deal accuratly with VAT for instance. But you are
already aware of that and I have no solution yet (not even time to think about it)

> Perhaps a further subdivision is needed.  The basic company setup in one
> document, accounting and localisation issues in a set of documents
> identified by country (or groups of countries where they do things
> sufficiently similarly), and then separate documents for the other bits
> like ecommerce, manufacturing and warehousing.
>
> Breaking the documentation up like this may also make it easier to get
> contributions as the task is less daunting.
>
> Just a thought.

Yes good plan, just have to rolling up our sleeves now :o)

Thanks for your interest !

> David

[Jacques Le Roux]

Sorry here is better information for tax part :
http://docs.ofbiz.org/display/OFBTECH/OFBiz%27s+Tax+Authority+Data+Model
(David and Jacopo are quick guys ;o)

Jacques

----- Original Message -----
From: "Jacques Le Roux" <[hidden email]>
To: <[hidden email]>
Sent: Saturday, December 30, 2006 4:08 PM
Subject: Re: An observation on Getting Started documentation

> David, all,
>
> ----- Original Message -----
> > I notice that the documentation for getting started has recently been split
> > in two, one technical the other business.  This is excellent and makes it
> > much easier to read.
>
> Yes I agree this is a very important point. I would say rather splitting between functionnal and technical concepts (in France we
> would say also "Organic" for the later part because it's only deals with structures and not functions) . But that's only words...
>
> > Reading the Business Setup document I am struck by the way in which it is
> > assumed that the only way to get started is to take the default seed data
> > and modify it, no-where does it describe how to start from scratch.
>
> Yes that's true, but at least there is something to help you, remember it's open source, you may help (acts, acts, acts, ...;o)

here

> of course...
>
> > When this is coupled with the discussion about who OfBiz is aiming at,
> > and which bits of what is a very extensive offering are regarded as basic
> > this has the effect that you end up disabling bits that you do not want
> > rather than enabling the bit that you want.  This also means that there
> > are things that are configured but about which you (the user) know nothing
> > and for which you have no use.
> >
> > Is the subtext that defining from scratch is so complicated that it should
> > never be attempted.  If so perhaps this should be stated.
>
> Easy way, but why not !
>
> > Of 15 pages (when I printed the document) basic company setup talks about
> > how to set up the basic business and occupies just one page, and then about
> > 10 page cover the ecommerce aspects.  Tax is only mentioned as an adjunct of
> > the ecommerce section, and the setup of the accounting section is not even
> > mentioned.
>
> About tax it's even worse : it's obsolete ! Please search for Tax Authotiries in Nabble to know more...
>
> > There is also no mention of localisation.  Getting OfBiz to default to other
> > than the Dollar and American style Sales tax (and I am aware of the recent
> > discussion on VAT on this list) is not mentioned, and worse, it is not
> > mentioned that what is being described is a US model.
>
> Yes that was already raised by Chris Howe here :
> http://www.nabble.com/-jira--Created%3A-%28OFBIZ-149%29-Better-describe-complex-party-relationships-tf2082963.html#a5772036
> And I believe also that something is missing in the data model to be able to deal accuratly with VAT for instance. But you are
> already aware of that and I have no solution yet (not even time to think about it)
>
> > Perhaps a further subdivision is needed.  The basic company setup in one
> > document, accounting and localisation issues in a set of documents
> > identified by country (or groups of countries where they do things
> > sufficiently similarly), and then separate documents for the other bits
> > like ecommerce, manufacturing and warehousing.
> >
> > Breaking the documentation up like this may also make it easier to get
> > contributions as the task is less daunting.
> >
> > Just a thought.
>
> Yes good plan, just have to rolling up our sleeves now :o)
>
> Thanks for your interest !
>
> > David
>

[David Goodenough]

On Saturday 30 December 2006 15:11, Jacques Le Roux wrote:
> Sorry here is better information for tax part :
> http://docs.ofbiz.org/display/OFBTECH/OFBiz%27s+Tax+Authority+Data+Model
> (David and Jacopo are quick guys ;o)
This is excellent "how it works" documentation, but does not tell you how
to use it.  That would obviously have to be part of the localisation docs.

David

>
> Jacques
>
> ----- Original Message -----
> From: "Jacques Le Roux" <[hidden email]>
> To: <[hidden email]>
> Sent: Saturday, December 30, 2006 4:08 PM
> Subject: Re: An observation on Getting Started documentation
>
> > David, all,
> >
> > ----- Original Message -----
> >
> > > I notice that the documentation for getting started has recently been
> > > split in two, one technical the other business.  This is excellent and
> > > makes it much easier to read.
> >
> > Yes I agree this is a very important point. I would say rather splitting
> > between functionnal and technical concepts (in France we would say also
> > "Organic" for the later part because it's only deals with structures and
> > not functions) . But that's only words...
> >
> > > Reading the Business Setup document I am struck by the way in which it
> > > is assumed that the only way to get started is to take the default seed
> > > data and modify it, no-where does it describe how to start from
> > > scratch.
> >
> > Yes that's true, but at least there is something to help you, remember
> > it's open source, you may help (acts, acts, acts, ...;o)
>
> here
>
> > of course...
> >
> > > When this is coupled with the discussion about who OfBiz is aiming at,
> > > and which bits of what is a very extensive offering are regarded as
> > > basic this has the effect that you end up disabling bits that you do
> > > not want rather than enabling the bit that you want.  This also means
> > > that there are things that are configured but about which you (the
> > > user) know nothing and for which you have no use.
> > >
> > > Is the subtext that defining from scratch is so complicated that it
> > > should never be attempted.  If so perhaps this should be stated.
> >
> > Easy way, but why not !
> >
> > > Of 15 pages (when I printed the document) basic company setup talks
> > > about how to set up the basic business and occupies just one page, and
> > > then about 10 page cover the ecommerce aspects.  Tax is only mentioned
> > > as an adjunct of the ecommerce section, and the setup of the accounting
> > > section is not even mentioned.
> >
> > About tax it's even worse : it's obsolete ! Please search for Tax
> > Authotiries in Nabble to know more...
> >
> > > There is also no mention of localisation.  Getting OfBiz to default to
> > > other than the Dollar and American style Sales tax (and I am aware of
> > > the recent discussion on VAT on this list) is not mentioned, and worse,
> > > it is not mentioned that what is being described is a US model.
> >
> > Yes that was already raised by Chris Howe here :
> > http://www.nabble.com/-jira--Created%3A-%28OFBIZ-149%29-Better-describe-c
> >omplex-party-relationships-tf2082963.html#a5772036 And I believe also that
> > something is missing in the data model to be able to deal accuratly with
> > VAT for instance. But you are already aware of that and I have no
> > solution yet (not even time to think about it)
> >
> > > Perhaps a further subdivision is needed.  The basic company setup in
> > > one document, accounting and localisation issues in a set of documents
> > > identified by country (or groups of countries where they do things
> > > sufficiently similarly), and then separate documents for the other bits
> > > like ecommerce, manufacturing and warehousing.
> > >
> > > Breaking the documentation up like this may also make it easier to get
> > > contributions as the task is less daunting.
> > >
> > > Just a thought.
> >
> > Yes good plan, just have to rolling up our sleeves now :o)
> >
> > Thanks for your interest !
> >
> > > David

[David E Jones-2]

Just a bit of a comment on this...

As a deceiving generality (but hopefully helpful nonetheless) there  
are two major ways to try to use OFBiz:

1. OOTB (Out Of The Box)
2. heavily customized, ie custom apps based on OFBiz

Of course, many users fall in between somewhere (hence my prelude).

The setup guides have two purposes as I see them, one for each of the  
groups mentioned above:

1. a way to get going quickly without worrying too much about how  
every little thing works (hence the starting with demo data)
2. a way to get the boot-strap an iterative development cycle and get  
to something quickly that can be the basis for review and planning  
for the initial iteration(s)

In general for #2 what Jacopo described is true. There is no way you  
can create a document aside from describing recommended OOTB use that  
would be applicable to any sort of majority of prospective users.  
Business and industries and individuals running businesses just vary  
to much.

Going forward we may try to address different industries more  
specifically OOTB so that they get what is more relevant to them.  
This is really the only way to provide something that is fairly  
complete and usable for small and medium sized business, and is why  
most enterprise app companies (including SAP) have industry-specific  
templates or packages to give people something close to an OOTB  
experience (ie one that does not involve a complete analysis, design,  
develop, test process for everything they might want to do with the  
software).

In general though, I highly recommend not trying to pigeon-hole OFBiz  
too much, even based on what people in the developer and leadership  
positions say (including me!).

OFBiz has been and always will be what people make it to be. In other  
words, OFBiz is a combination of what dozens of companies in various  
industries, but mostly in retail and manufacturing, have needed.

As a side note on accounting: you should note that most of the  
accounting setup (outside of basic payment and invoice processing) is  
handled best using the financials module from Open Source Strategies.  
Unfortunately that is a separate project from OFBiz and we can't  
change that until one of two things happens: either OSS decides to  
contribute it, or someone groups enough resources to create a clean-
room implementation that serves that same general requirement. In  
other words, for accounting setup regarding which accounts to post to  
and what not, the documentation from Open Source Strategies is the  
only way to go (of which there certainly is some pretty good stuff).  
It doesn't even really make sense for us to document that along with  
the OFBiz documentation, though if Si wanted to add in links to his  
stuff or comments clearly marked as relating to it, then I think  
that's fine and great as it will make things easier for end-users.

As always, enjoy! And yeah, if you're interested in documentation  
submitting some proposed changes would be great, and if you really  
want to get into I'd be happy to give you change privileges there on  
a trial basis.

-David



On Dec 30, 2006, at 4:41 AM, David Goodenough wrote:

> I notice that the documentation for getting started has recently  
> been split
> in two, one technical the other business.  This is excellent and  
> makes it
> much easier to read.
>
> Reading the Business Setup document I am struck by the way in which  
> it is
> assumed that the only way to get started is to take the default  
> seed data
> and modify it, no-where does it describe how to start from scratch.
>
> When this is coupled with the discussion about who OfBiz is aiming at,
> and which bits of what is a very extensive offering are regarded as  
> basic
> this has the effect that you end up disabling bits that you do not  
> want
> rather than enabling the bit that you want.  This also means that  
> there
> are things that are configured but about which you (the user) know  
> nothing
> and for which you have no use.
>
> Is the subtext that defining from scratch is so complicated that it  
> should
> never be attempted.  If so perhaps this should be stated.
>
> Of 15 pages (when I printed the document) basic company setup talks  
> about
> how to set up the basic business and occupies just one page, and  
> then about
> 10 page cover the ecommerce aspects.  Tax is only mentioned as an  
> adjunct of
> the ecommerce section, and the setup of the accounting section is  
> not even
> mentioned.
>
> There is also no mention of localisation.  Getting OfBiz to default  
> to other
> than the Dollar and American style Sales tax (and I am aware of the  
> recent
> discussion on VAT on this list) is not mentioned, and worse, it is not
> mentioned that what is being described is a US model.
>
> Perhaps a further subdivision is needed.  The basic company setup  
> in one
> document, accounting and localisation issues in a set of documents
> identified by country (or groups of countries where they do things
> sufficiently similarly), and then separate documents for the other  
> bits
> like ecommerce, manufacturing and warehousing.
>
> Breaking the documentation up like this may also make it easier to get
> contributions as the task is less daunting.
>
> Just a thought.
>
> David