The problem with documentation in general is of course, 1st to create it, but
thereafter especially to keep up to date.
So I understand Scott's POV. But, on the other hand, applications components are now stablised. We dont' expect much changes there.
So we should not have too much work updating help files. In summary, I finally don't agree to create an intermediary step with wiki
and script to transform. We have already a structure (I mean in general, not only what Pierre created and hopefully will now fill
with documentation) which handles i18n, why complicate things? People can contribute through Jira, an alternative route is not
needed.
This said, I see why Jacopo is suggesting to use the wiki. A lot of efforts by the commity, not only in the help, have been aborted
or no completed. And then, us, committers, need to cope with the burden of maintaining or finally removing. Currently the main goal
of the community should be the slim-down action. It's not contradictory to also fix bugs, or add help documentation, or even add new
features. But we should try to focus on the slim-down. Everybody should undertstand that, not only committers. I hope, at this
stage, I don't need to explain why.
Jacques
From: "Pierre Smits" <[email protected]>
Indeed an interesting expression of thoughts.
When I read a statement like 'the committers can't maintain potentially
thousands of help files and records', I cannot help but think that you
don't maintain it. You merely click a virtual button in a piece of software
that upload changes to a system. The help files and records are maintained
by volunteers in the OFBiz community.
And I read that it is you against them. Not with them. You don't even talk
about 'we, the community, anymore! And in order to maintain or even expand
that distance between you and the community, you'll be even going so fas as
to create yet another piece of 'decent work' to totally avoid being a part
of that Open Source community.
You should be ashamed of yourself!
2012/5/11 Jacopo Cappellato <[email protected]>
Interesting conversation... but I would like to clarify that what I was
suggesting was to use Confluence as the sandbox to prepare content (to
simplify the cooperation of the community and in parallel waiting for the
discussion about the best format to use to finalize).
Jacopo
On May 11, 2012, at 11:16 AM, Adrian Crum wrote:
> On 5/11/2012 9:57 AM, Jacques Le Roux wrote:
>> From: "Jacopo Cappellato" <[email protected]>
>>> On May 11, 2012, at 9:55 AM, Jacques Le Roux wrote:
>>>
>>>> This makes sense Scott! We could even link the help from wiki online
for demos. The problem is we use Confluence and its export
>>>> is known to be flawed and not supported/mantained anymore.
>>>
>>> That is not related to what Scott was saying: the Confluence
autoexport is related to the ability to transform a Confluence page
>>> into a static html page.
>>>
>>>>
>>>> I think it can be continued this way in the meantime.
>>>
>>> I disagree that we should continue to add incomplete stuff to the
trunk (and release branches) until a better design is in place.
>>> This will not stop the huge effort of creating documentation and
actual content for the help screens: contributors can do this in
>>> Confluence (or similar) and then, when we will have defined a good
design it will be easy to write a script to import the content
>>> into the new format.
>>
>> How to handle i18n automatisation in Confluence? Though yes, it's not
really automated in online help as well, since we need to
>> create as much files as languages.
>>
>
> The approach I use is to include the help URLs in the UI label files -
so each translation can have its own URL. The URLs can point to content
generated within OFBiz, or to an external site.
>
> -Adrian
