Posted by
Vinay Agarwal on
Mar 29, 2006; 11:46pm
URL: http://ofbiz.116.s1.nabble.com/Users-Updated-documentation-tp138178p138191.html
I believe we should focus on developing tools (customized IDE) as much as
documentation. Even if perfect documentation were to be available for OFBiz,
a newbie would still have a very long ramp up time since
1. Documentation for something as complex as OFBiz won't be small.
2. The number of technologies need to be understood are a lot (Java,
minilang, xml, html, javascript, widgets, ftl, ant etc). One has to know
sufficiently about them in order to read the code and make even minor mods.
The best example I have seen an IDE alleviate need for a lot of reading is
Visual Studio which does a good job of making skeleton code for commonly
used but complex tasks. NetBeans 5 has a very basic "code writing"
capability for pure Java. And I understand that IntelliJ IDEA has some
built-in capabilities for some popular frameworks. If we can get an IDE to
build skeleton file/function structure for commonly used items, it would go
a long way to speed up newbies and may even increase efficiency of experts.
Regards,
Vinay Agarwal
-----Original Message-----
From:
[hidden email] [mailto:
[hidden email]]
On Behalf Of Adrian Crum
Sent: Wednesday, March 29, 2006 11:12 AM
To: OFBiz Users / Usage Discussion
Subject: Re: [OFBiz] Users - Updated documentation ...
I like this idea BJ, but online help only works after the installation is
running. It's good to mention this though, because it would be nice to have
an
online help system reference the "official" documentation (in whatever form
it
becomes) once the installation is running.
Take the database questions that come up frequently as an example. On the
mailing list, users are referred to the Webtools page, Wiki, past mailings,
etc.
Let's say that information is collected and distilled into the OFBiz
documentation. If someone is setting up a new installation and OFBiz won't
start
because of DB issues, then an online help system won't be of much use. They
will
have to access the documentation in some other way. Once the system is up
and
running, clicking on Help from the Webtools page would take them to the same
DB
documentation they referenced earlier.
BJ Freeman wrote:
> David I agree with the site you have, even as a commercial venture.
> However I believe there should be division between the code that
> supports the site and the data in the site.
>
> I ask about a help framework earlier, that this would answer. However it
> is not to duplicate your data, but to put user specific help based on my
> modification. I doubt my help files would be an any interest, unless my
> mods are being used.
>
> Now if you feel that part of the cost could be re-coupled for the code
> segment, then I believe that should be separate from the actual support
> site you maintain.
>
> Maybe the Code could be such that all but the localize help would go to
> your site.
>
> Just some thoughts.
>
> David E. Jones sent the following on 3/29/06 10:29 AM:
>
>>This does bring up an interesting discussion point: how should we manage
end-user oriented documentation (and other documentation too...)?
>>
>>Notice that I did _not_ ask what would everyone like to see in the
documentation... that is a moot point without a way to go about getting it
in place. I'd rather not talk about that as it has been discussed quite a
bit, it confuses the point of how to get things done and who will do them,
and often leads to blaming those who have contributed to OFBiz for not
contributing even more.
>>
>>The eventual form of the documentation is another problem, made more
difficult by the fact that depending on how you look at it there are either
many targets or one moving target to go after...
>>
>>The Undersun documentation site is something Andy and I started pushing a
while back and is built (mostly by Al Byers) on the OFBiz content component.
The actual content (images and text) are maintained and mostly written by
Les who is a technical writer we are contracting with to maintain it.
>>
>>This is commercial rather than collaborative in nature because
collaborative attempts in the past at OFBiz documentation have failed so
completely that nothing has been written except isolated pockets of
documentation (including the "official" documentation on the ofbiz.org site)
that we not only don't get many (or any) contributions, but we almost never
even get feedback on the documentation.
>>
>>I think this is largely by the nature of documentation. When most people
say they want "documentation" what they really want is understanding of the
software either technical or business and end user level. The hope of
documentation is to get people to those points of understanding as quickly
as possible, but initially even seeing the size of the documentation and the
options available can be a serious "gumption trap". For a great discussion
on gumption traps I recommend the book "Zen and the Art of Motorcycle
Maintenance" by Robert Pirsig.
>>
>>Anyway, back the real issue...
>>
>>My hope with the Undersun site is that it would become more collaborative.
Those who are interested in contributing have been given free accounts to
the site. We have a nearly full-time technical writer on contract to help
maintain the information so that it can hopefully remain more consistent and
better controlled.
>>
>>If people object to the commercial nature of it, ie we charge for access
to the site on a subscription basis, then that's fine. If there are other
alternative it would be great. So far the site is not profitable, not even
close to profitable. In fact, Andy and I subsidize the site pretty heavily
in hopes that someday it will pay for itself, and in the mean time we
believe it is important to the success of OFBiz to have end-user oriented
documentation, and so we continue to invest what little we can in it.
>>
>>I would appreciate any feedback anyone might have. In general it would
also be great to see more invested in this and other documentation efforts
as it is one of a few areas of OFBiz that could use some work.
>>
>>-David
>>
>>
>>
>>Ian Gilbert wrote:
>>
>>
>>>Hi All,
>>>
>>>I'm glad they are popular :) I am happy to release these under any
license but I'm not sure that
>>>this will have the desired effect. My reasoning is that the development
community (that this doc
>>>is not really targeted at) has a range of resources to pull information
from (wiki, production
>>>guide, mailing lists, intro docs on the Open Source Strategies site, the
Undersun Consulting docs
>>>etc.,) but most of my users are non tech and would simply get lost in the
information. Indeed
>>>they would not even consider contributing back and probably would have
difficulties understanding
>>>the concept. Certainly there would be hurdles to stop them (I cannot see
them using Jira for
>>>example although I can see them deluging me with the same emails a few
hundred times). There is
>>>not too much user orientated resource available at the moment but this is
understandable because
>>>the type of business user who has got involved in the project so far have
all had a considerable
>>>technical ability and inclination.
>>>
>>>We have quite a high turnover of people at ES and so it made a lot of
sense to write some form of
>>>training or user reference doc simply to reduce the amount of time that I
was spending with people
>>>on the same questions. I think that there is still lots to do on this
(similar books run to 5-600
>>>pages in the shops so I'm not going to stop now ;) Granted I've skipped
the traditional
>>>'Introduction to the Internet' which most of them have (don't worry guys
- it will be in the next
>>>version) but even so there is a huge amount still to cover even with the
limited way in which we
>>>use Ofbiz. I was also keen to create a doc that could be pulled apart
and used as a test script
>>>as much of the UAT we do is much easier that way.
>>>
>>>The reason I don't think it will work in the community in the same way is
that there are very few
>>>end users (or appear to be) on the list that wouldn't be better off
updating the wiki. I've used
>>>Open Office to create the DocBook format (it was the first of these that
I've done and I do like
>>>it but would like to use another editor to create new tags which I think
might end up with a more
>>>flexible document (i.e. use one document root to create sub docs for
Administrators, store clerks,
>>>accounts team etc., which should be quite straightforward with xml) but I
have to fit this into
>>>gaps between contracts like the one I've got right now.
>>>
>>>That said I'm happy for this to be released under any license and for
anyone to use this in any
>>>way they see fit. Considering the value that ES and I have had from
participating in this project
>>>it really is the least I can do. At some point I would like to write a
more professional guide
>>>and ideally have it published properly. I think that this would be
better created with a number
>>>of authors simply because the subject is so big.
>>>
>>>Very best wishes
>>>
>>>Ian
>>>
>>>
>>>
>>>
>>>On Wed, March 29, 2006 12:28, David Welton wrote:
>>>
>>>
>>>>>>Yes, nice job indeed. It would be good to see something like this
>>>>>>distributed with OFBiz itself.
>>>>>
>>>>>Yes, or maybe a link from official OFBiz site (Doc tab) will be
sufficient ?
>>>>>
>>>>
>>>>As the years go by, stuff that doesn't get held together tends to
>>>>float apart (bit rot). Perhaps if the DocBook sources were in
Subversion, more people would update
>>>>them and add to them, as well. However, this is a decision for Ian, who
would have to release the
>>>>docs under a suitable license, and the developers, who would have to
choose to include it.
_______________________________________________
Users mailing list
[hidden email]
http://lists.ofbiz.org/mailman/listinfo/users
_______________________________________________
Users mailing list
[hidden email]
http://lists.ofbiz.org/mailman/listinfo/users