Users - who would like to write documentation?

[Si Chen-2]

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

[Ray Barlow]

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

[davidnwelton]

> 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.

Like anything else, docs are something that happens because someone
sits down and creates them, like Ian did.  Often, once you have an
initial 'catalyst', at the very least, it can be maintained as is and
kept up to date, because it's much easier tweaking something that
writing new docs from scratch.

--
David N. Welton
 - http://www.dedasys.com/davidw/

Linux, Open Source Consulting
 - http://www.dedasys.com/
 
_______________________________________________
Users mailing list
[hidden email]
http://lists.ofbiz.org/mailman/listinfo/users

[Daniel Kunkel]

Thank you Ray...

You've made some great comments. A few additional thoughts come up...

There are currently too many choices about where to put documentation...
And, when I have a question, too many places to search. I think we would
all be better served by creating one free resource to build the
documentation.

E-mail

These e-mail lists, although a wonderful resource that I wouldn't want
to change, may be part of the problem. We have loads of incredible
information that flows through the e-mail system, and then is never seen
again.

Searching through e-mails is difficult as evidenced by the questions and
issues that are repeated periodically.

Wiki

My experience suggests that the Wiki could be far far better if it were
tended.

In general, most people who spend a long time searching for an answer
will be kind enough to share the fruits of their labor if there is one
clear appropriate easy place to add that information. This could be in
the form a blog type system where people can add notes to an existing
documentation page, or a wiki, as we've seen, sometimes just via e-mail.

Wiki Tending

No one, including myself has been watching and comparing the commits to
the previous version to combine or edit changes as appropriate with the
exception of when the site has been hit by spam. I therefore can
completely understand Ian's reluctance to release his great
documentation on Wiki, since there doesn't seem to be the facility to
watch for modifications...  and without that he reasonabily would rather
forgo the improvements others might make to forgo seeing his well
organized and useful document reduced to chaos


A proposal...

Would it be possible to tie the Wiki into the e-mail system. This way,
when a revision, or question that the questioner thinks deserves a place
in the wiki, the stub would already be started, and the e-mail thread
could be recorded right into the system.

Then, as Ray noted, once the core information is present, the gracious
readers will often gladly rewrite the entries for those that follow...

Thanks







On Fri, 2006-03-31 at 13:54 +0100, Ray wrote:

> 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

 
_______________________________________________
Users mailing list
[hidden email]
http://lists.ofbiz.org/mailman/listinfo/users

[Jacques Le Roux]

Daniel,

Just one information

From: "Daniel Kunkel" <[hidden email]>

>
> No one, including myself has been watching and comparing the commits to
> the previous version to combine or edit changes as appropriate with the
> exception of when the site has been hit by spam. I therefore can
> completely understand Ian's reluctance to release his great
> documentation on Wiki, since there doesn't seem to be the facility to
> watch for modifications...

There is a way to watch for modifications. I use Sage in Firefox for this. But I
must admit that it's rather a crude tool. And you have to watch periodically to
follow modifications (every week seems sufficient).
While awaiting better...

Jacques

 
_______________________________________________
Users mailing list
[hidden email]
http://lists.ofbiz.org/mailman/listinfo/users