incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rob Weir <robw...@apache.org>
Subject Re: Symphony documentation for AOO?
Date Sat, 17 Mar 2012 12:52:10 GMT
On Sat, Mar 17, 2012 at 12:43 AM, Jingbai <jingbaibetsy@gmail.com> wrote:
> In Symphony,
> 1) the editing env is a tool called ID workbench for editing Dita files
> 2) Documentation source file format is Dita
> 3) Help files published on two places On IEHS(IBM Eclipse Help system ) together with
the product in Eclipse framework as the offline version
> On Wiki system as the online version.
> I think for AOO, we could create docs in the products as before and import to Wiki as
well. It is essential to let the help files be accessible though the internet or google searched
and getting comments directly
> The thing is we do not have to use a complex editing env or file format so that we could
avoid to create the technical barrier for volunteers. Need to learn more about the Apache
supported Wiki system requirement to let the editing env as simple as possible.
> Thoughts?

Here is an example of the Confluence Wiki:

https://cwiki.apache.org/confluence/display/OOOUSERS/Wiki+Home

And here is an example of our MediaWiki:

http://wiki.services.openoffice.org/wiki/Documentation/Administration_Guide/Using_Custom_Macros_and_Libraries

You can sign up for an account on both systems.

I agree with the goal of getting the documentation onto the web, so it
can be indexed by Google and count by users trying to find answers by
searching.

But I think wiki is just one option. Another would be to convert to HTML, right?

So there are a few possibilities to consider:

1) Can we make OpenOffice read and write DITA?  So use a familiar
editing tool (OpenOffice) but have it understand DITA.

Advantage:  Reuse existing Symphony content directly.  Familiar
authoring environment for documentation writers.

Disadvantage:  Would require development work to enable OpenOffice to
read/write DITA.  (But this would also be a wonderful feature for
other users as well, since DITA is an industry standard format for
technical writing)

2) Can we convert the existing Symphony documentation into ODF format,
so it can be maintained in OpenOffice?

Advantage:  We use familiar authoring environment, OpenOffice

Disadvantage: By moving away from DITA we lose some of the
capabilities to transform into other formats easily.

3) Can we support a hybrid solution where we have both DITA doc and
existing OOo doc, but unify things at publication time, by all
targeting the same output formats, like PDF and HTML

Advantage: Least amount of change required

Disadvantage: Complexity, greater difficulty in maintaining uniform
presentation styles on output

-Rob


> Betsy
> 发自我的 iPhone
>
> 在 2012-3-17,上午9:03,Rob Weir <robweir@apache.org> 写道:
>
>> On Fri, Mar 16, 2012 at 7:26 PM, Guy Waterval <waterval.guy@gmail.com> wrote:
>>> Hello Betsy,
>>>
>>>
>>> 2012/3/16 Jing Bai <jingbaibetsy@gmail.com>
>>>
>>>> Seems many people would agree that WIKI solution is a good one. Does anyone
>>>> know where we can find the WIKI hardware and platform resources in our
>>>> community? How could we setup one wiki platform for ourselves to host the
>>>> help?
>>>>
>>>
>>> Concerning this question of documentation,  I totally subscribe with the
>>> position of Jean Weber when she says :
>>>
>>> [Citation] : I also think many of the volunteers who worked on user
>>> guides for OOo -- if they choose to work on AOO docs -- prefer to work in
>>> AOO itself and produce user guides that demonstrate (some of) what one
>>> can do with the product as a publishing system. [End of citation]
>>>
>>> Moreover, I think that the choice of the wiki or the DITA format would
>>> introduce a technical barrier which would strongly reduce the number of
>>> volunteers. Please, consider that such a group as the LO fr group, which
>>> has began to translate the LO oooauthors docs, seems to have some
>>> difficulties to reach the necessary team to do the job. For me, the number
>>> of people involved does nos exceed 4 or 5. This can give you an idea of the
>>> difficulty to create a documentation team of volunteers, even when working
>>> with a well known method.
>>>
>>
>> The format isn't the issue. The issue is the editing environment,
>> right? If you could use OpenOffice as your editor and easily save it
>> to DITA, or Wiki format, then that would be OK.  Do you agree?
>>
>> If so, I think there are three questions to consider:
>>
>> 1) What editing environment(s) should we support?
>>
>> 2) What format should we use for storing the documentations in its
>> richest (fullest) form?
>>
>> 3) What publication format(s) should we publish the documentation in?
>>
>> If I understand the way the ODFAuthors are working, the choices were:
>> 1=OpenOffice, 2= ODF, 3=PDF.  Is that correct?
>>
>> Jinbai, how is it for Symphony?  1=?, 2=DITA, 3= Wiki ?
>>
>>
>> -Rob
>>
>>
>>> Of course, if the community choose another way, I will try to participate,
>>> even if I never have worked with a wiki.
>>>
>>> A+
>>>
>>> --
>>>
>>> gw

Mime
View raw message