Hi Scott:
IMO, the reality is that the very same people who make excellent
software developers do not or cannot write. As you may know, good
writing is not about "dumping" words into a Wiki. Good writing is a
skill, developed over many hours (dare I say years) of work. Writing
involves much more than putting words to paper. Organization, structure,
editing and re-editing, layout and finally publication are some of the
many components of a well written document.
The Wiki concept brings out the lazy writer in all of us. True, it is
well suited to the "community" software development process. No one in
the community is required to document anything. Worse yet, Wiki entries
no matter how incomprehensible, contradictory or confusing may be
written with impunity. [Try doing that with software commits.]
My point: Anyone who has built a house (and I've done lots of home
rehabs) knows that the tools "make the man" - or in my case, the woman.
Regards,
Ruth
Scott Gray wrote:
I agree with Jacques, it is not a tool issue (or at least not
primarily). The reality is that very few people spend any time long
term working on OFBiz documentation and the result is that the wiki
ends up being a bit of dumping ground for information. Unless there
is a tool that magically edits and organizes information into well
structured documentation I doubt much would change regardless of what
tool we use.
Regards
Scott
HotWax Media
http://www.hotwaxmedia.com
On 30/10/2009, at 6:43 AM, Jacques Le Roux wrote:
Hi Ruth,
We could also organize things the same way than in a book in Confluence.
It has all we need for that, but as long as we don't coordinate our
work any kind of tool will not be useful regarding this issue
I still think it's an organisation problem. But how to organize the
work of a free community is another question that any authoring tool
will not resolve intrinsically.
Also, I remember one of the things that made the community considers
Confluence a good tool for our use was the possibility it offers with
permissions.
As I already said these projects use also Confluence (on Apache
infrastructure)
http://servicemix.apache.org/home.html
http://geronimo.apache.org/
As you can see, there are a "bit more" organised than our Wiki. For
instance, only the left part allows to embrace the project at a
glance. Something we definitively lack at
http://docs.ofbiz.org/dashboard.action
I think we can do as good if we decide to do it. For the most part,
this does not depend of the tool, or even the kind of tool you use,
it depends of the women/men who use them.
I don't know if it's a lack of community maturity or an inclination
of our community, or more certainmy a trivial lack of ressources, ie
manpower... (Geronimo and ServiceMix have both big supporters...)
Jacques
From: "Ruth Hoffman" <[email protected]>
Hi Jacques:
I think it is a tool problem. I've come to believe, after 25+ years
of struggling with the best way to convey complex, multi-dimensional
ideas and concepts, that the "Wiki" format for documentation
presentation is just about useless for most users - especially new
users. The problem, as I see it is that a Wiki has only one
dimension - even the most carefully crafted Wiki has but one
dimension - that of the Wiki itself. A project such as OFBiz has
many dimensions, is constantly changing and has many target audiences.
Wikis seem to work best as repositories for small snippets of
information. Kind-of like a bunch of sticky notes positioned around
the office. The problem is that unless you were the author and
depositor of those sticky notes, others will only randomly happen
upon them. Even under the best search and organizational conditions,
finding the right set of sticky notes for the task at hand can be a
real challenge.
My solution has been to fall back on writing traditional
documentation organized and targeted at specific audiences. I don't
know if the DocBookWiki would provide a framework for building more
traditional (and I would argue useful) information sources as I
haven't looked at it. But now that you have given me the idea, I am
going to take a look.
Thanks Chris.
Just my 2 cents :-)
Ruth
Jacques Le Roux wrote:
Hi Chris,
I sincerely think it's not a tool problem but simply lack of
community organisation.
Also, despite the lack of organisation, lot efforts have already
been put in the wiki and moving to another support, DocBookWiki or
whatever, will need to be very carefully done!
Last but not least, the commuity ambition, would be to use OFBiz
itself to support its own wiki. Ambitious isn'it ?
Licence : Confluence is Atlassian property (as Jira which uses
OFBiz Entity Engine internally, BTW), in other word it's a
commercial product. But like some other companies, Atlassian offers
graciously some licences. I believe, the one we currently use was
donated to Undersun (the consulting company David and Andy created
when the begin to work on OFBiz) and is now used on an HWM server.
In the meantime (before using OFBize itself) we should move to
Apacher servers since Atlassian has also offered a licence to the
ASF https://issues.apache.org/jira/browse/INFRA-1877. Confluence is
already used by other major ASF projects : Geronimo, ServiceMix, to
list a few...
HTH
Jacques
From: "Christopher Snow" <[email protected]>
I was wondering how useful people find the ofbiz wiki.
It seems that there is a lot of very good information on the wiki,
but it just doesn't seem to be structured (structure is precisely
what new users need, along with product stability).
I've been looking at the DocBookWiki project and although it has a
long way to go to be usable, it allows you to structure your wiki
like you would a book - see example on
http://doc-book.sourceforge.net/books/. It also has links to
generate different formats from your wiki including docbook, html
and pdf.
What is the license for the contents of the ofbiz wiki? Would I
be allowed to use the content on the wiki and combine it into
another format?
Many thanks,
Chris
