Posted by
Ray Barlow on
Mar 31, 2006; 12:54pm
URL: http://ofbiz.116.s1.nabble.com/Users-who-would-like-to-write-documentation-tp138256p138257.html
I think the silence speaks for itself ;-)
Maybe that's a little unfair as I think although several people have and
still would and do provide docs you've asked for specific commitment and
that is certainly harder to give. For example we have produced a POS doc
but I can't commit to taking on the POS module as I don't have a lot of
resource to monitor changes that might get made directly or indirectly
to the POS module. Certainly I'll update what I can when I can.
Personally I think it does matter which system you use as proven by the
current segmentation of sites, formats and licenses and this discussion
coming up again (seems like this time last year we visited it):
Wiki - Easy for anybody to access and help maintain, but that is why
some core developers view it's content as a little on the wild side.
Probably also a little cumbersome to do good docs in it as the
style/formatting control is not the best, really want WYSIWYG.
Ofbiz web - Clean, controlled and lots of good stuff there, but also
lots of dated stuff. The reality has proven that most developers are
busy patching code and patches for the docs just don't get done. Scaling
up input to this area might seem like a good idea but that would
increase the cost on the core developers controlling it's SVN commits,
so it needs a mechanism change as well.
Undersun docs - A difficult one to describe as I can't comment on how
accurate and up to date it is with the latest SVN features and
functions, but understand that is it's target position. Also I have no
idea how many people are adding to it and maintaining it, beyond the
mentioned technical writer and some developers.
OpenSourceStrategies - Some great docs here and a must visit location
for most OFBiz adopters. Correct me if I'm wrong but I suspect not a
large amount of community support back in to it. Would be nice to see it
merge more into a central repos.
To sum those areas up I would say the Wiki has the highest amount of
input and turn over from the community, which suggests that it has
something in it's favour to the people that you want to help with the
docs. Yes at the moment it is not controlled enough and the formatting
control for good docs is weak, but a CMS tool like lenya or opencms
would probably go a long way to fixing that. Overall site structure and
control could be closely maintained, whilst handing more access out to
other users to control and manage the content. I like the "anybody can
post comments at the bottom" idea, it can be used to submit changes that
get reviewed and applied or not, you've got to have a quick and easy
method for change submission for all users not just developers that can
work svn magic.
Another major contributor to the docs would be if developers added a
paragraph or two when creating new features. Even poorly written rough
notes, or bullet points help a lot more than a blank sheet of paper.
Retrospective documentation is very costly and error prone when done by
somebody outside of the original loop.
Ray
Si Chen wrote:
>Hi everybody.
>
>I've found the discussion on user documentation pretty interesting. One
>issue, however, still remains: no matter what system you use, somebody
>has to write them. So who could actually commit to writing and
>maintaining user documentation for, say, various modules of ofbiz?
>
>Si
>
>
>_______________________________________________
>Users mailing list
>
[hidden email]
>
http://lists.ofbiz.org/mailman/listinfo/users>
>
>
_______________________________________________
Users mailing list
[hidden email]
http://lists.ofbiz.org/mailman/listinfo/users