Page Linked User Documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Page Linked User Documentation

Daniel Kunkel
Hi

I've got what I think is an awesome idea for improving the end user
experience easily with page links to user documentation.

The idea is pretty simple I think...  Essentially most every page of the
OFBiz web application would get an "Instruction for this Page" link.
This link would then take the user to page describing the page and how
to use it.

The implementation is a little more difficult, since I'm uncertain where
is the best place to locate the instruction.

My first thought is to create a centralized OFBiz wiki. This way the
content would be developed and improved easily by the user community as
a whole, for the benefit of everyone.

However, this doesn't conform to the style, formating, or system
modifications that may make the documents inappropriate for some
installation.

The next thought then, is to create an OFBiz sub web-site. The
formatting could be controlled by the maincss helping with the
formatting, and can be changed. However, it's much more difficult to
develop and deliver than with a wiki.

Finally, it seems that the instructions could be embedded into seed or
demo data, and become part of the final user's website. This seems like
it might work even better, but is probably the hardest to develope and
configure.

Thanks
--
Daniel

*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-
Have a GREAT Day!

Daniel Kunkel           [hidden email]
BioWaves, LLC           http://www.BioWaves.com
14150 NE 20th St. Suite F1
Bellevue, WA 98007
800-734-3588    425-895-0050
http://www.Apartment-Pets.com  http://www.Illusion-Optical.com
http://www.Card-Offer.com      http://www.RackWine.com
http://www.JokesBlonde.com     http://www.Brain-Fun.com 
*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-

Reply | Threaded
Open this post in threaded view
|

Re: Page Linked User Documentation

cjhowe
Ugh, it's been a while.  Probably more than a year ago there was a wiki
firefox extension that would allow you to wiki about any website on the
net.  I'll look for it.

Additionally, a relatively simple way is to use the approach on :
http://ofbizwiki.go-integral.com/Wiki.jsp?page=FAQ21

All you would change in the new app/apps is the header in the
main-decorator.  

It has been suggested that every full screen definition should have a
body tag id that makes it unique to ease css styling anyway.  
ie:
<set field="bodyId" value="catalogMain"/>

So in the header of the new app you create a link
<a href="http://docs.ofbiz.org/display/OFBIZ/${bodyId}">click here for
help</a>

Now if you use the new apps instead of the current ones, you'll have
the link and the only thing you'll have to monitor is updates to
controller.xml for that app.  But that should be changing soon as well
as David perfects some work on ecomclone.

--- Daniel Kunkel <[hidden email]> wrote:

> Hi
>
> I've got what I think is an awesome idea for improving the end user
> experience easily with page links to user documentation.
>
> The idea is pretty simple I think...  Essentially most every page of
> the
> OFBiz web application would get an "Instruction for this Page" link.
> This link would then take the user to page describing the page and
> how
> to use it.
>
> The implementation is a little more difficult, since I'm uncertain
> where
> is the best place to locate the instruction.
>
> My first thought is to create a centralized OFBiz wiki. This way the
> content would be developed and improved easily by the user community
> as
> a whole, for the benefit of everyone.
>
> However, this doesn't conform to the style, formating, or system
> modifications that may make the documents inappropriate for some
> installation.
>
> The next thought then, is to create an OFBiz sub web-site. The
> formatting could be controlled by the maincss helping with the
> formatting, and can be changed. However, it's much more difficult to
> develop and deliver than with a wiki.
>
> Finally, it seems that the instructions could be embedded into seed
> or
> demo data, and become part of the final user's website. This seems
> like
> it might work even better, but is probably the hardest to develope
> and
> configure.
>
> Thanks
> --
> Daniel
>
> *-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-
> Have a GREAT Day!
>
> Daniel Kunkel           [hidden email]
> BioWaves, LLC           http://www.BioWaves.com
> 14150 NE 20th St. Suite F1
> Bellevue, WA 98007
> 800-734-3588    425-895-0050
> http://www.Apartment-Pets.com  http://www.Illusion-Optical.com
> http://www.Card-Offer.com      http://www.RackWine.com
> http://www.JokesBlonde.com     http://www.Brain-Fun.com 
> *-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-.,,.-*"*-
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Page Linked User Documentation

jonwimp
In reply to this post by Daniel Kunkel
Daniel,

Great idea. We're working on that right now.

Only problem with creating such in-application help texts is we first have to fully document OFBiz
before we even know what to put in such in-app help texts. We're also working on that right now.

In case our full user manual is clear enough, then we might skip the work needed to build in-app
help texts.

 > Finally, it seems that the instructions could be embedded into seed or demo
 > data, and become part of the final user's website. This seems like it might
 > work even better, but is probably the hardest to develope and configure.

I vote for this method. It's the most OOTB approach. But I don't suggest putting the help texts in
database. It's easy enough ("duh" kind of easy) to create help texts inside individual webapp/
folders.

Also, consider the case where we customize OFBiz for individual clients. Each customized OFBiz
will probably have different functionalities (tweaked/modified from original), and they'll all
require their own Help texts.

Creating a centralized Help site (say http://ofbiz.apache.org/help) will too tightly couple
individual OFBiz instances (including customized instances) to the one-size-fits-all Help site.

Jonathon

Daniel Kunkel wrote:

> Hi
>
> I've got what I think is an awesome idea for improving the end user
> experience easily with page links to user documentation.
>
> The idea is pretty simple I think...  Essentially most every page of the
> OFBiz web application would get an "Instruction for this Page" link.
> This link would then take the user to page describing the page and how
> to use it.
>
> The implementation is a little more difficult, since I'm uncertain where
> is the best place to locate the instruction.
>
> My first thought is to create a centralized OFBiz wiki. This way the
> content would be developed and improved easily by the user community as
> a whole, for the benefit of everyone.
>
> However, this doesn't conform to the style, formating, or system
> modifications that may make the documents inappropriate for some
> installation.
>
> The next thought then, is to create an OFBiz sub web-site. The
> formatting could be controlled by the maincss helping with the
> formatting, and can be changed. However, it's much more difficult to
> develop and deliver than with a wiki.
>
> Finally, it seems that the instructions could be embedded into seed or
> demo data, and become part of the final user's website. This seems like
> it might work even better, but is probably the hardest to develope and
> configure.
>
> Thanks

Reply | Threaded
Open this post in threaded view
|

Re: Page Linked User Documentation

Andrew Sykes
In reply to this post by Daniel Kunkel
Daniel,

This has been discussed before, I think it was Hans Bakker who last
proposed it. There was a fair bit of discussion at the time...

- Andrew

On Mon, 2007-01-29 at 09:47 +0800, Jonathon -- Improov wrote:

> Daniel,
>
> Great idea. We're working on that right now.
>
> Only problem with creating such in-application help texts is we first have to fully document OFBiz
> before we even know what to put in such in-app help texts. We're also working on that right now.
>
> In case our full user manual is clear enough, then we might skip the work needed to build in-app
> help texts.
>
>  > Finally, it seems that the instructions could be embedded into seed or demo
>  > data, and become part of the final user's website. This seems like it might
>  > work even better, but is probably the hardest to develope and configure.
>
> I vote for this method. It's the most OOTB approach. But I don't suggest putting the help texts in
> database. It's easy enough ("duh" kind of easy) to create help texts inside individual webapp/
> folders.
>
> Also, consider the case where we customize OFBiz for individual clients. Each customized OFBiz
> will probably have different functionalities (tweaked/modified from original), and they'll all
> require their own Help texts.
>
> Creating a centralized Help site (say http://ofbiz.apache.org/help) will too tightly couple
> individual OFBiz instances (including customized instances) to the one-size-fits-all Help site.
>
> Jonathon
>
> Daniel Kunkel wrote:
> > Hi
> >
> > I've got what I think is an awesome idea for improving the end user
> > experience easily with page links to user documentation.
> >
> > The idea is pretty simple I think...  Essentially most every page of the
> > OFBiz web application would get an "Instruction for this Page" link.
> > This link would then take the user to page describing the page and how
> > to use it.
> >
> > The implementation is a little more difficult, since I'm uncertain where
> > is the best place to locate the instruction.
> >
> > My first thought is to create a centralized OFBiz wiki. This way the
> > content would be developed and improved easily by the user community as
> > a whole, for the benefit of everyone.
> >
> > However, this doesn't conform to the style, formating, or system
> > modifications that may make the documents inappropriate for some
> > installation.
> >
> > The next thought then, is to create an OFBiz sub web-site. The
> > formatting could be controlled by the maincss helping with the
> > formatting, and can be changed. However, it's much more difficult to
> > develop and deliver than with a wiki.
> >
> > Finally, it seems that the instructions could be embedded into seed or
> > demo data, and become part of the final user's website. This seems like
> > it might work even better, but is probably the hardest to develope and
> > configure.
> >
> > Thanks
>
--
Kind Regards
Andrew Sykes <[hidden email]>
Sykes Development Ltd
http://www.sykesdevelopment.com

Reply | Threaded
Open this post in threaded view
|

Re: Page Linked User Documentation

David E Jones

There is some great news about this! As Andrew mentioned this has  
been discussed before, even years ago.

Even better, the resting place for this documentation has already  
been decided! It will go with the rest of the end-user oriented  
documentation on the docs.ofbiz.org site. It will go in the  
OFBENDUSER space:

http://docs.ofbiz.org/pages/listpages-dirview.action?key=OFBENDUSER

And more specifically this sort of material, reference material for  
specific screens, will go under the "Manager References" document here:

http://docs.ofbiz.org/x/RAI

You'll see some early efforts here from Ray Barlow that are based on  
the Undersun doc site exports, which all need to be moved to the wiki  
format, and which are all available in PDF dump form here:

http://docs.ofbiz.org/x/5gI

So, as you can see this effort is already well underway. As different  
areas are cleaned up refined and reorganized we can start linking to  
them in the applications.

There is a LOT more work right now needed for this to get an initial  
pass done, and then there will be more help needed over time. So for  
anyone that has time and interest to invest in this, please do!

-David


On Jan 29, 2007, at 1:57 AM, Andrew Sykes wrote:

> Daniel,
>
> This has been discussed before, I think it was Hans Bakker who last
> proposed it. There was a fair bit of discussion at the time...
>
> - Andrew
>
> On Mon, 2007-01-29 at 09:47 +0800, Jonathon -- Improov wrote:
>> Daniel,
>>
>> Great idea. We're working on that right now.
>>
>> Only problem with creating such in-application help texts is we  
>> first have to fully document OFBiz
>> before we even know what to put in such in-app help texts. We're  
>> also working on that right now.
>>
>> In case our full user manual is clear enough, then we might skip  
>> the work needed to build in-app
>> help texts.
>>
>>> Finally, it seems that the instructions could be embedded into  
>>> seed or demo
>>> data, and become part of the final user's website. This seems  
>>> like it might
>>> work even better, but is probably the hardest to develope and  
>>> configure.
>>
>> I vote for this method. It's the most OOTB approach. But I don't  
>> suggest putting the help texts in
>> database. It's easy enough ("duh" kind of easy) to create help  
>> texts inside individual webapp/
>> folders.
>>
>> Also, consider the case where we customize OFBiz for individual  
>> clients. Each customized OFBiz
>> will probably have different functionalities (tweaked/modified  
>> from original), and they'll all
>> require their own Help texts.
>>
>> Creating a centralized Help site (say http://ofbiz.apache.org/ 
>> help) will too tightly couple
>> individual OFBiz instances (including customized instances) to the  
>> one-size-fits-all Help site.
>>
>> Jonathon
>>
>> Daniel Kunkel wrote:
>>> Hi
>>>
>>> I've got what I think is an awesome idea for improving the end user
>>> experience easily with page links to user documentation.
>>>
>>> The idea is pretty simple I think...  Essentially most every page  
>>> of the
>>> OFBiz web application would get an "Instruction for this Page" link.
>>> This link would then take the user to page describing the page  
>>> and how
>>> to use it.
>>>
>>> The implementation is a little more difficult, since I'm  
>>> uncertain where
>>> is the best place to locate the instruction.
>>>
>>> My first thought is to create a centralized OFBiz wiki. This way the
>>> content would be developed and improved easily by the user  
>>> community as
>>> a whole, for the benefit of everyone.
>>>
>>> However, this doesn't conform to the style, formating, or system
>>> modifications that may make the documents inappropriate for some
>>> installation.
>>>
>>> The next thought then, is to create an OFBiz sub web-site. The
>>> formatting could be controlled by the maincss helping with the
>>> formatting, and can be changed. However, it's much more difficult to
>>> develop and deliver than with a wiki.
>>>
>>> Finally, it seems that the instructions could be embedded into  
>>> seed or
>>> demo data, and become part of the final user's website. This  
>>> seems like
>>> it might work even better, but is probably the hardest to  
>>> develope and
>>> configure.
>>>
>>> Thanks
>>
> --
> Kind Regards
> Andrew Sykes <[hidden email]>
> Sykes Development Ltd
> http://www.sykesdevelopment.com
>


smime.p7s (3K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Page Linked User Documentation

Daniel Kunkel
Hi

First, I apologize for any implication that it was my original idea. I
was just excited about what I think is a great idea.

Second...  That's great to see that the idea has moved forward, and that
some difficult decisions have already been made and do not need to be
rehashed.

Taking a step back and looking at the process, I realize that for
someone like Jonathan, it was unlikely to find out that this feature had
already been started. Is there a place where we keep a list of these
types of efforts?  I was not able to find mention of it in jira, but
that may still be the best place for this for now.

Thanks

Daniel



On Mon, 2007-01-29 at 03:30 -0700, David E. Jones wrote:

> There is some great news about this! As Andrew mentioned this has  
> been discussed before, even years ago.
>
> Even better, the resting place for this documentation has already  
> been decided! It will go with the rest of the end-user oriented  
> documentation on the docs.ofbiz.org site. It will go in the  
> OFBENDUSER space:
>
> http://docs.ofbiz.org/pages/listpages-dirview.action?key=OFBENDUSER
>
> And more specifically this sort of material, reference material for  
> specific screens, will go under the "Manager References" document here:
>
> http://docs.ofbiz.org/x/RAI
>
> You'll see some early efforts here from Ray Barlow that are based on  
> the Undersun doc site exports, which all need to be moved to the wiki  
> format, and which are all available in PDF dump form here:
>
> http://docs.ofbiz.org/x/5gI
>
> So, as you can see this effort is already well underway. As different  
> areas are cleaned up refined and reorganized we can start linking to  
> them in the applications.
>
> There is a LOT more work right now needed for this to get an initial  
> pass done, and then there will be more help needed over time. So for  
> anyone that has time and interest to invest in this, please do!
>
> -David
>
>
> On Jan 29, 2007, at 1:57 AM, Andrew Sykes wrote:
>
> > Daniel,
> >
> > This has been discussed before, I think it was Hans Bakker who last
> > proposed it. There was a fair bit of discussion at the time...
> >
> > - Andrew
> >
> > On Mon, 2007-01-29 at 09:47 +0800, Jonathon -- Improov wrote:
> >> Daniel,
> >>
> >> Great idea. We're working on that right now.
> >>
> >> Only problem with creating such in-application help texts is we  
> >> first have to fully document OFBiz
> >> before we even know what to put in such in-app help texts. We're  
> >> also working on that right now.
> >>
> >> In case our full user manual is clear enough, then we might skip  
> >> the work needed to build in-app
> >> help texts.
> >>
> >>> Finally, it seems that the instructions could be embedded into  
> >>> seed or demo
> >>> data, and become part of the final user's website. This seems  
> >>> like it might
> >>> work even better, but is probably the hardest to develope and  
> >>> configure.
> >>
> >> I vote for this method. It's the most OOTB approach. But I don't  
> >> suggest putting the help texts in
> >> database. It's easy enough ("duh" kind of easy) to create help  
> >> texts inside individual webapp/
> >> folders.
> >>
> >> Also, consider the case where we customize OFBiz for individual  
> >> clients. Each customized OFBiz
> >> will probably have different functionalities (tweaked/modified  
> >> from original), and they'll all
> >> require their own Help texts.
> >>
> >> Creating a centralized Help site (say http://ofbiz.apache.org/ 
> >> help) will too tightly couple
> >> individual OFBiz instances (including customized instances) to the  
> >> one-size-fits-all Help site.
> >>
> >> Jonathon
> >>
> >> Daniel Kunkel wrote:
> >>> Hi
> >>>
> >>> I've got what I think is an awesome idea for improving the end user
> >>> experience easily with page links to user documentation.
> >>>
> >>> The idea is pretty simple I think...  Essentially most every page  
> >>> of the
> >>> OFBiz web application would get an "Instruction for this Page" link.
> >>> This link would then take the user to page describing the page  
> >>> and how
> >>> to use it.
> >>>
> >>> The implementation is a little more difficult, since I'm  
> >>> uncertain where
> >>> is the best place to locate the instruction.
> >>>
> >>> My first thought is to create a centralized OFBiz wiki. This way the
> >>> content would be developed and improved easily by the user  
> >>> community as
> >>> a whole, for the benefit of everyone.
> >>>
> >>> However, this doesn't conform to the style, formating, or system
> >>> modifications that may make the documents inappropriate for some
> >>> installation.
> >>>
> >>> The next thought then, is to create an OFBiz sub web-site. The
> >>> formatting could be controlled by the maincss helping with the
> >>> formatting, and can be changed. However, it's much more difficult to
> >>> develop and deliver than with a wiki.
> >>>
> >>> Finally, it seems that the instructions could be embedded into  
> >>> seed or
> >>> demo data, and become part of the final user's website. This  
> >>> seems like
> >>> it might work even better, but is probably the hardest to  
> >>> develope and
> >>> configure.
> >>>
> >>> Thanks
> >>
> > --
> > Kind Regards
> > Andrew Sykes <[hidden email]>
> > Sykes Development Ltd
> > http://www.sykesdevelopment.com
> >
>

Reply | Threaded
Open this post in threaded view
|

Re: Page Linked User Documentation

David E Jones

On Jan 29, 2007, at 9:33 AM, Daniel Kunkel wrote:

> Taking a step back and looking at the process, I realize that for
> someone like Jonathan, it was unlikely to find out that this  
> feature had
> already been started. Is there a place where we keep a list of these
> types of efforts?  I was not able to find mention of it in jira, but
> that may still be the best place for this for now.

This is a constant problem, especially for efforts like this with no  
current activity. The only way to find out about it is to search  
mailing list archives, which is never easy of course as figuring out  
the keywords to use is not always trivial and may not include  
everything you were hoping to find due to different terms being used.

On the other hand, the current documentation does pretty clearly  
address this area and is around 2 and 4 clicks from the home page of  
the docs.ofbiz.org site. So, maybe reading browsing through the  
existing documentation or in general whatever is similar to what you  
are thinking about can be helpful.

-David



smime.p7s (3K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Page Linked User Documentation

jonwimp
In reply to this post by Daniel Kunkel
Daniel,

Yup, you're right. I started looking at online OFBiz resources sometime Dec 07, very briefly;
spent most time in quickly comparing many opensource EPR apps (and on other projects). And then in
Jan 07, I seriously dug through online OFBiz resources. Couldn't find much, broken/missing
linkages between related docs, generally very disjointed experience. So much so that I had to dig
into the codes to find "documentation".

I'm not saying how it should've been done (lots of work to organize docs in a navigation-friendly
way to 1st-time visitors). I'm just stating a fact that you've correctly observed (for me and for
many other newbies).

I think all these problems will be resolved gradually over time. First thing we might wanna do is
to really attract and keep newbies (haven't heard from Mike Wong :(, wonder if his bosses voted
against OFBiz).

Jonathon

Daniel Kunkel wrote:

> Hi
>
> First, I apologize for any implication that it was my original idea. I
> was just excited about what I think is a great idea.
>
> Second...  That's great to see that the idea has moved forward, and that
> some difficult decisions have already been made and do not need to be
> rehashed.
>
> Taking a step back and looking at the process, I realize that for
> someone like Jonathan, it was unlikely to find out that this feature had
> already been started. Is there a place where we keep a list of these
> types of efforts?  I was not able to find mention of it in jira, but
> that may still be the best place for this for now.
>
> Thanks
>
> Daniel
>
>
>
> On Mon, 2007-01-29 at 03:30 -0700, David E. Jones wrote:
>> There is some great news about this! As Andrew mentioned this has  
>> been discussed before, even years ago.
>>
>> Even better, the resting place for this documentation has already  
>> been decided! It will go with the rest of the end-user oriented  
>> documentation on the docs.ofbiz.org site. It will go in the  
>> OFBENDUSER space:
>>
>> http://docs.ofbiz.org/pages/listpages-dirview.action?key=OFBENDUSER
>>
>> And more specifically this sort of material, reference material for  
>> specific screens, will go under the "Manager References" document here:
>>
>> http://docs.ofbiz.org/x/RAI
>>
>> You'll see some early efforts here from Ray Barlow that are based on  
>> the Undersun doc site exports, which all need to be moved to the wiki  
>> format, and which are all available in PDF dump form here:
>>
>> http://docs.ofbiz.org/x/5gI
>>
>> So, as you can see this effort is already well underway. As different  
>> areas are cleaned up refined and reorganized we can start linking to  
>> them in the applications.
>>
>> There is a LOT more work right now needed for this to get an initial  
>> pass done, and then there will be more help needed over time. So for  
>> anyone that has time and interest to invest in this, please do!
>>
>> -David
>>
>>
>> On Jan 29, 2007, at 1:57 AM, Andrew Sykes wrote:
>>
>>> Daniel,
>>>
>>> This has been discussed before, I think it was Hans Bakker who last
>>> proposed it. There was a fair bit of discussion at the time...
>>>
>>> - Andrew
>>>
>>> On Mon, 2007-01-29 at 09:47 +0800, Jonathon -- Improov wrote:
>>>> Daniel,
>>>>
>>>> Great idea. We're working on that right now.
>>>>
>>>> Only problem with creating such in-application help texts is we  
>>>> first have to fully document OFBiz
>>>> before we even know what to put in such in-app help texts. We're  
>>>> also working on that right now.
>>>>
>>>> In case our full user manual is clear enough, then we might skip  
>>>> the work needed to build in-app
>>>> help texts.
>>>>
>>>>> Finally, it seems that the instructions could be embedded into  
>>>>> seed or demo
>>>>> data, and become part of the final user's website. This seems  
>>>>> like it might
>>>>> work even better, but is probably the hardest to develope and  
>>>>> configure.
>>>> I vote for this method. It's the most OOTB approach. But I don't  
>>>> suggest putting the help texts in
>>>> database. It's easy enough ("duh" kind of easy) to create help  
>>>> texts inside individual webapp/
>>>> folders.
>>>>
>>>> Also, consider the case where we customize OFBiz for individual  
>>>> clients. Each customized OFBiz
>>>> will probably have different functionalities (tweaked/modified  
>>>> from original), and they'll all
>>>> require their own Help texts.
>>>>
>>>> Creating a centralized Help site (say http://ofbiz.apache.org/ 
>>>> help) will too tightly couple
>>>> individual OFBiz instances (including customized instances) to the  
>>>> one-size-fits-all Help site.
>>>>
>>>> Jonathon
>>>>
>>>> Daniel Kunkel wrote:
>>>>> Hi
>>>>>
>>>>> I've got what I think is an awesome idea for improving the end user
>>>>> experience easily with page links to user documentation.
>>>>>
>>>>> The idea is pretty simple I think...  Essentially most every page  
>>>>> of the
>>>>> OFBiz web application would get an "Instruction for this Page" link.
>>>>> This link would then take the user to page describing the page  
>>>>> and how
>>>>> to use it.
>>>>>
>>>>> The implementation is a little more difficult, since I'm  
>>>>> uncertain where
>>>>> is the best place to locate the instruction.
>>>>>
>>>>> My first thought is to create a centralized OFBiz wiki. This way the
>>>>> content would be developed and improved easily by the user  
>>>>> community as
>>>>> a whole, for the benefit of everyone.
>>>>>
>>>>> However, this doesn't conform to the style, formating, or system
>>>>> modifications that may make the documents inappropriate for some
>>>>> installation.
>>>>>
>>>>> The next thought then, is to create an OFBiz sub web-site. The
>>>>> formatting could be controlled by the maincss helping with the
>>>>> formatting, and can be changed. However, it's much more difficult to
>>>>> develop and deliver than with a wiki.
>>>>>
>>>>> Finally, it seems that the instructions could be embedded into  
>>>>> seed or
>>>>> demo data, and become part of the final user's website. This  
>>>>> seems like
>>>>> it might work even better, but is probably the hardest to  
>>>>> develope and
>>>>> configure.
>>>>>
>>>>> Thanks
>>> --
>>> Kind Regards
>>> Andrew Sykes <[hidden email]>
>>> Sykes Development Ltd
>>> http://www.sykesdevelopment.com
>>>
>
>

Reply | Threaded
Open this post in threaded view
|

RE: Page Linked User Documentation

mikeymwong
Jonathon,

I'm still here and am very busy preparing the demonstration on coming Thu...

Mike

-----Original Message-----
From: Jonathon -- Improov [mailto:[hidden email]]
Sent: Tuesday, January 30, 2007 11:55 AM
To: [hidden email]
Subject: Re: Page Linked User Documentation

Daniel,

Yup, you're right. I started looking at online OFBiz resources sometime Dec
07, very briefly;
spent most time in quickly comparing many opensource EPR apps (and on other
projects). And then in
Jan 07, I seriously dug through online OFBiz resources. Couldn't find much,
broken/missing
linkages between related docs, generally very disjointed experience. So much
so that I had to dig
into the codes to find "documentation".

I'm not saying how it should've been done (lots of work to organize docs in
a navigation-friendly
way to 1st-time visitors). I'm just stating a fact that you've correctly
observed (for me and for
many other newbies).

I think all these problems will be resolved gradually over time. First thing
we might wanna do is
to really attract and keep newbies (haven't heard from Mike Wong :(, wonder
if his bosses voted
against OFBiz).

Jonathon

Daniel Kunkel wrote:

> Hi
>
> First, I apologize for any implication that it was my original idea. I
> was just excited about what I think is a great idea.
>
> Second...  That's great to see that the idea has moved forward, and that
> some difficult decisions have already been made and do not need to be
> rehashed.
>
> Taking a step back and looking at the process, I realize that for
> someone like Jonathan, it was unlikely to find out that this feature had
> already been started. Is there a place where we keep a list of these
> types of efforts?  I was not able to find mention of it in jira, but
> that may still be the best place for this for now.
>
> Thanks
>
> Daniel
>
>
>
> On Mon, 2007-01-29 at 03:30 -0700, David E. Jones wrote:
>> There is some great news about this! As Andrew mentioned this has  
>> been discussed before, even years ago.
>>
>> Even better, the resting place for this documentation has already  
>> been decided! It will go with the rest of the end-user oriented  
>> documentation on the docs.ofbiz.org site. It will go in the  
>> OFBENDUSER space:
>>
>> http://docs.ofbiz.org/pages/listpages-dirview.action?key=OFBENDUSER
>>
>> And more specifically this sort of material, reference material for  
>> specific screens, will go under the "Manager References" document here:
>>
>> http://docs.ofbiz.org/x/RAI
>>
>> You'll see some early efforts here from Ray Barlow that are based on  
>> the Undersun doc site exports, which all need to be moved to the wiki  
>> format, and which are all available in PDF dump form here:
>>
>> http://docs.ofbiz.org/x/5gI
>>
>> So, as you can see this effort is already well underway. As different  
>> areas are cleaned up refined and reorganized we can start linking to  
>> them in the applications.
>>
>> There is a LOT more work right now needed for this to get an initial  
>> pass done, and then there will be more help needed over time. So for  
>> anyone that has time and interest to invest in this, please do!
>>
>> -David
>>
>>
>> On Jan 29, 2007, at 1:57 AM, Andrew Sykes wrote:
>>
>>> Daniel,
>>>
>>> This has been discussed before, I think it was Hans Bakker who last
>>> proposed it. There was a fair bit of discussion at the time...
>>>
>>> - Andrew
>>>
>>> On Mon, 2007-01-29 at 09:47 +0800, Jonathon -- Improov wrote:
>>>> Daniel,
>>>>
>>>> Great idea. We're working on that right now.
>>>>
>>>> Only problem with creating such in-application help texts is we  
>>>> first have to fully document OFBiz
>>>> before we even know what to put in such in-app help texts. We're  
>>>> also working on that right now.
>>>>
>>>> In case our full user manual is clear enough, then we might skip  
>>>> the work needed to build in-app
>>>> help texts.
>>>>
>>>>> Finally, it seems that the instructions could be embedded into  
>>>>> seed or demo
>>>>> data, and become part of the final user's website. This seems  
>>>>> like it might
>>>>> work even better, but is probably the hardest to develope and  
>>>>> configure.
>>>> I vote for this method. It's the most OOTB approach. But I don't  
>>>> suggest putting the help texts in
>>>> database. It's easy enough ("duh" kind of easy) to create help  
>>>> texts inside individual webapp/
>>>> folders.
>>>>
>>>> Also, consider the case where we customize OFBiz for individual  
>>>> clients. Each customized OFBiz
>>>> will probably have different functionalities (tweaked/modified  
>>>> from original), and they'll all
>>>> require their own Help texts.
>>>>
>>>> Creating a centralized Help site (say http://ofbiz.apache.org/ 
>>>> help) will too tightly couple
>>>> individual OFBiz instances (including customized instances) to the  
>>>> one-size-fits-all Help site.
>>>>
>>>> Jonathon
>>>>
>>>> Daniel Kunkel wrote:
>>>>> Hi
>>>>>
>>>>> I've got what I think is an awesome idea for improving the end user
>>>>> experience easily with page links to user documentation.
>>>>>
>>>>> The idea is pretty simple I think...  Essentially most every page  
>>>>> of the
>>>>> OFBiz web application would get an "Instruction for this Page" link.
>>>>> This link would then take the user to page describing the page  
>>>>> and how
>>>>> to use it.
>>>>>
>>>>> The implementation is a little more difficult, since I'm  
>>>>> uncertain where
>>>>> is the best place to locate the instruction.
>>>>>
>>>>> My first thought is to create a centralized OFBiz wiki. This way the
>>>>> content would be developed and improved easily by the user  
>>>>> community as
>>>>> a whole, for the benefit of everyone.
>>>>>
>>>>> However, this doesn't conform to the style, formating, or system
>>>>> modifications that may make the documents inappropriate for some
>>>>> installation.
>>>>>
>>>>> The next thought then, is to create an OFBiz sub web-site. The
>>>>> formatting could be controlled by the maincss helping with the
>>>>> formatting, and can be changed. However, it's much more difficult to
>>>>> develop and deliver than with a wiki.
>>>>>
>>>>> Finally, it seems that the instructions could be embedded into  
>>>>> seed or
>>>>> demo data, and become part of the final user's website. This  
>>>>> seems like
>>>>> it might work even better, but is probably the hardest to  
>>>>> develope and
>>>>> configure.
>>>>>
>>>>> Thanks
>>> --
>>> Kind Regards
>>> Andrew Sykes <[hidden email]>
>>> Sykes Development Ltd
>>> http://www.sykesdevelopment.com
>>>
>
>




Reply | Threaded
Open this post in threaded view
|

Re: Page Linked User Documentation

jonwimp
Hi Mike!

Nice to hear from you again. Let us know if you need quick help for your preparations!

(Don't respond to this, or we'll be hijacking this thread! We'll talk in another thread.)

Jonathon

Mike Wong wrote:

> Jonathon,
>
> I'm still here and am very busy preparing the demonstration on coming Thu...
>
> Mike
>
> -----Original Message-----
> From: Jonathon -- Improov [mailto:[hidden email]]
> Sent: Tuesday, January 30, 2007 11:55 AM
> To: [hidden email]
> Subject: Re: Page Linked User Documentation
>
> Daniel,
>
> Yup, you're right. I started looking at online OFBiz resources sometime Dec
> 07, very briefly;
> spent most time in quickly comparing many opensource EPR apps (and on other
> projects). And then in
> Jan 07, I seriously dug through online OFBiz resources. Couldn't find much,
> broken/missing
> linkages between related docs, generally very disjointed experience. So much
> so that I had to dig
> into the codes to find "documentation".
>
> I'm not saying how it should've been done (lots of work to organize docs in
> a navigation-friendly
> way to 1st-time visitors). I'm just stating a fact that you've correctly
> observed (for me and for
> many other newbies).
>
> I think all these problems will be resolved gradually over time. First thing
> we might wanna do is
> to really attract and keep newbies (haven't heard from Mike Wong :(, wonder
> if his bosses voted
> against OFBiz).
>
> Jonathon
>
> Daniel Kunkel wrote:
>> Hi
>>
>> First, I apologize for any implication that it was my original idea. I
>> was just excited about what I think is a great idea.
>>
>> Second...  That's great to see that the idea has moved forward, and that
>> some difficult decisions have already been made and do not need to be
>> rehashed.
>>
>> Taking a step back and looking at the process, I realize that for
>> someone like Jonathan, it was unlikely to find out that this feature had
>> already been started. Is there a place where we keep a list of these
>> types of efforts?  I was not able to find mention of it in jira, but
>> that may still be the best place for this for now.
>>
>> Thanks
>>
>> Daniel
>>
>>
>>
>> On Mon, 2007-01-29 at 03:30 -0700, David E. Jones wrote:
>>> There is some great news about this! As Andrew mentioned this has  
>>> been discussed before, even years ago.
>>>
>>> Even better, the resting place for this documentation has already  
>>> been decided! It will go with the rest of the end-user oriented  
>>> documentation on the docs.ofbiz.org site. It will go in the  
>>> OFBENDUSER space:
>>>
>>> http://docs.ofbiz.org/pages/listpages-dirview.action?key=OFBENDUSER
>>>
>>> And more specifically this sort of material, reference material for  
>>> specific screens, will go under the "Manager References" document here:
>>>
>>> http://docs.ofbiz.org/x/RAI
>>>
>>> You'll see some early efforts here from Ray Barlow that are based on  
>>> the Undersun doc site exports, which all need to be moved to the wiki  
>>> format, and which are all available in PDF dump form here:
>>>
>>> http://docs.ofbiz.org/x/5gI
>>>
>>> So, as you can see this effort is already well underway. As different  
>>> areas are cleaned up refined and reorganized we can start linking to  
>>> them in the applications.
>>>
>>> There is a LOT more work right now needed for this to get an initial  
>>> pass done, and then there will be more help needed over time. So for  
>>> anyone that has time and interest to invest in this, please do!
>>>
>>> -David
>>>
>>>
>>> On Jan 29, 2007, at 1:57 AM, Andrew Sykes wrote:
>>>
>>>> Daniel,
>>>>
>>>> This has been discussed before, I think it was Hans Bakker who last
>>>> proposed it. There was a fair bit of discussion at the time...
>>>>
>>>> - Andrew
>>>>
>>>> On Mon, 2007-01-29 at 09:47 +0800, Jonathon -- Improov wrote:
>>>>> Daniel,
>>>>>
>>>>> Great idea. We're working on that right now.
>>>>>
>>>>> Only problem with creating such in-application help texts is we  
>>>>> first have to fully document OFBiz
>>>>> before we even know what to put in such in-app help texts. We're  
>>>>> also working on that right now.
>>>>>
>>>>> In case our full user manual is clear enough, then we might skip  
>>>>> the work needed to build in-app
>>>>> help texts.
>>>>>
>>>>>> Finally, it seems that the instructions could be embedded into  
>>>>>> seed or demo
>>>>>> data, and become part of the final user's website. This seems  
>>>>>> like it might
>>>>>> work even better, but is probably the hardest to develope and  
>>>>>> configure.
>>>>> I vote for this method. It's the most OOTB approach. But I don't  
>>>>> suggest putting the help texts in
>>>>> database. It's easy enough ("duh" kind of easy) to create help  
>>>>> texts inside individual webapp/
>>>>> folders.
>>>>>
>>>>> Also, consider the case where we customize OFBiz for individual  
>>>>> clients. Each customized OFBiz
>>>>> will probably have different functionalities (tweaked/modified  
>>>>> from original), and they'll all
>>>>> require their own Help texts.
>>>>>
>>>>> Creating a centralized Help site (say http://ofbiz.apache.org/ 
>>>>> help) will too tightly couple
>>>>> individual OFBiz instances (including customized instances) to the  
>>>>> one-size-fits-all Help site.
>>>>>
>>>>> Jonathon
>>>>>
>>>>> Daniel Kunkel wrote:
>>>>>> Hi
>>>>>>
>>>>>> I've got what I think is an awesome idea for improving the end user
>>>>>> experience easily with page links to user documentation.
>>>>>>
>>>>>> The idea is pretty simple I think...  Essentially most every page  
>>>>>> of the
>>>>>> OFBiz web application would get an "Instruction for this Page" link.
>>>>>> This link would then take the user to page describing the page  
>>>>>> and how
>>>>>> to use it.
>>>>>>
>>>>>> The implementation is a little more difficult, since I'm  
>>>>>> uncertain where
>>>>>> is the best place to locate the instruction.
>>>>>>
>>>>>> My first thought is to create a centralized OFBiz wiki. This way the
>>>>>> content would be developed and improved easily by the user  
>>>>>> community as
>>>>>> a whole, for the benefit of everyone.
>>>>>>
>>>>>> However, this doesn't conform to the style, formating, or system
>>>>>> modifications that may make the documents inappropriate for some
>>>>>> installation.
>>>>>>
>>>>>> The next thought then, is to create an OFBiz sub web-site. The
>>>>>> formatting could be controlled by the maincss helping with the
>>>>>> formatting, and can be changed. However, it's much more difficult to
>>>>>> develop and deliver than with a wiki.
>>>>>>
>>>>>> Finally, it seems that the instructions could be embedded into  
>>>>>> seed or
>>>>>> demo data, and become part of the final user's website. This  
>>>>>> seems like
>>>>>> it might work even better, but is probably the hardest to  
>>>>>> develope and
>>>>>> configure.
>>>>>>
>>>>>> Thanks
>>>> --
>>>> Kind Regards
>>>> Andrew Sykes <[hidden email]>
>>>> Sykes Development Ltd
>>>> http://www.sykesdevelopment.com
>>>>
>>
>
>
>
>
>