Online help Confluence space

[Bruno Busco <br...@gmail.com>]

Hi,
I am going to create an help page for every OFBiz screen so that these
could be exported and linked to OFBiz as a locallly deployed on-line
help.
(please see https://issues.apache.org/jira/browse/OFBIZ-2133)

I wonder if we should keep the actual Confluence page naming pattern
like here http://docs.ofbiz.org/display/OFBIZ/Accounting+Manager

In this care very OFBiz page has a number that is a menu position.
This will be a problem if a menu command is added or deleted.
I propose to have all the page names without numbers. Do you agree ?

A related question is: should we use the Open for businness project
Wiki space to host this help pages so that everybody can contribute to
it or shoul we use the OFBiz End User documentation space that is
restricted in writing to committers?
I think the first option will be better. Do you agree ?

Many thanks,
Bruno

Re: Online help Confluence space

[Jacques Le Roux <ja...@les7arts.com>]

From: "Bruno Busco" <br...@gmail.com>
To: <de...@ofbiz.apache.org>
Sent: Thursday, February 12, 2009 7:21 PM
Subject: Online help Confluence space


> Hi,
> I am going to create an help page for every OFBiz screen so that these
> could be exported and linked to OFBiz as a locallly deployed on-line
> help.
> (please see https://issues.apache.org/jira/browse/OFBIZ-2133)
> 
> I wonder if we should keep the actual Confluence page naming pattern
> like here http://docs.ofbiz.org/display/OFBIZ/Accounting+Manager
> 
> In this care very OFBiz page has a number that is a menu position.
> This will be a problem if a menu command is added or deleted.
> I propose to have all the page names without numbers. Do you agree ?

Already answered in OFBIZ-2133
 
> A related question is: should we use the Open for businness project
> Wiki space to host this help pages so that everybody can contribute to
> it or shoul we use the OFBiz End User documentation space that is
> restricted in writing to committers?
> I think the first option will be better. Do you agree ?

Yes I agree, Sharan has proved it can work! We "just" need qualified volunters like her...

Jacques
 
> Many thanks,
> Bruno
>

Re: Online help Confluence space

[David E Jones <da...@hotwaxmedia.com>]

On Feb 12, 2009, at 11:21 AM, Bruno Busco wrote:

> Hi,
> I am going to create an help page for every OFBiz screen so that these
> could be exported and linked to OFBiz as a locallly deployed on-line
> help.
> (please see https://issues.apache.org/jira/browse/OFBIZ-2133)
>
> I wonder if we should keep the actual Confluence page naming pattern
> like here http://docs.ofbiz.org/display/OFBIZ/Accounting+Manager
>
> In this care very OFBiz page has a number that is a menu position.
> This will be a problem if a menu command is added or deleted.
> I propose to have all the page names without numbers. Do you agree ?
>
> A related question is: should we use the Open for businness project
> Wiki space to host this help pages so that everybody can contribute to
> it or shoul we use the OFBiz End User documentation space that is
> restricted in writing to committers?

The end user space is not actually restricted to committers, anyone  
who volunteers to work on documentation can have access to it. For a  
while only those who volunteered to work on docs had access, but we  
changed it to include all committers by default.

Early on a few people were roped into doing documentation, you could  
maybe call them volunteers... ;) Anyway, finding people to work on  
documentation is difficult, especially on a dedicated effort over a  
period of time which is what the access controlled space is all about.

The wiki/open space is a lot more popular because there are fewer  
constraints, but these are also the downsides to the resulting  
documentation there:

1. don't have to worry about how to organize the docs, just write  
about what you want to and stick it in a new page
2. don't have to worry about redundant content
3. don't have to worry about maintaining the content over time if/when  
things change
4. no qualifications required, and often the work is only checked by  
people who need the documentation and may not know if something is  
correct or not

In other words, the bar is very low and that is great because it means  
documentation actually gets written. While not always true, usually  
some documentation is better than no documentation.

> I think the first option will be better. Do you agree ?

What is better is a good question, but maybe not applicable. IMO the  
restricted space with more dedicated volunteers is "better", but not  
realistic. Chances are we'll have more content by simply opening it up  
and letting anyone work on it whenever they want. If we have enough  
volunteers we could move to a restricted space and make it more  
"official" content and invite people who have worked on it to continue  
to work on it and give them permissions, etc. Without enough  
volunteers it's a moot point, it's like a project in the ASF Incubator  
that dies because it can't find enough volunteers to work on it and so  
the restricted access model breaks down.

-David