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
Locked
