trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jin, Jian (Seth)" <Jian....@esgyn.cn>
Subject RE: [DISCUSS] Move documentation to Apache Open Office (AOO)
Date Mon, 14 Nov 2016 02:59:24 GMT
Hi Gunnar,

I agree with you. The documents are very important and we are translating documents into Chinese
version, if we cannot get diff between current and previous version, it is nightmare for translator.
Also by current way to compile documents, it is too complicated for non-technical contributors,
better to find easier way so that more potential contributors come in our community.

Br,

Seth

-----Original Message-----
From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com] 
Sent: 2016年11月14日 2:50
To: dev@trafodion.incubator.apache.org
Subject: Re: [DISCUSS] Move documentation to Apache Open Office (AOO)

Here's where I'm coming from:

1. Recently, I was approached by a colleague that wanted to contribute some documentation
changes. I explained how you have to set up a build environment, download the source, learn
asciidoc, build the documentation, etc. The result: an e-mail with the proposed changes. The
y barrier for non-developer contribution is way to high.
2. With a few exceptions, I don't see much of review of documentation. I see even less contribution.
It's worse than I've seen in project that use word processors and a simpler review process.
3. Any user experience material has to be seen in context. Diff documentation works OK for
code but not for UIs, documentation, etc.
4. I recently reorganized and amended the Client Install Guide. A job that should have taken
a few hours took way more time. There are a few other guides that would benefit from a similar
exercise but I'm unlikely to pursue the needed changes because of how arduous the task is.
5. We should translate the documentation to Chinese. We had the possibility to get tech writers
involved. Without word processor, it's not happening.

Gunnar

On Sat, Nov 12, 2016 at 9:02 PM, Venkat Muthuswamy < venkat.muthuswamy@esgyn.com> wrote:

> I agree with Steve. Using a text format document helps a lot in 
> reviewing and change tracking and selectively merge changes. And it 
> helps with the history log.
>
> -----Original Message-----
> From: Steve Varnau [mailto:steve.varnau@esgyn.com]
> Sent: Friday, November 11, 2016 1:07 PM
> To: dev@trafodion.incubator.apache.org
> Subject: RE: [DISCUSS] Move documentation to Apache Open Office (AOO)
>
> Personally, I like to be able to see diffs in text. I understand that 
> writing and especially formatting them is a pain in markup languages.  
> So there is a big win in usability to author in a non-text format.
>
> My biggest concern is in the traditional version control aspects. If 
> the docs are stored in non-text format, how can they be merged using 
> git. If they can't be merged, then only one person can work on a 
> document at a time? And how do you port a change from one release to another?
>
> Likewise, how do reviewers see the deltas easily in the review process.
>
> --Steve
>
> > -----Original Message-----
> > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > Sent: Friday, November 11, 2016 12:54 PM
> > To: dev@trafodion.incubator.apache.org
> > Subject: [DISCUSS] Move documentation to Apache Open Office (AOO)
> >
> > Hi,
> >
> > It's not easy to document in asciidoc. Personally, I have flashbacks 
> > to TGAL/TFORM (for you old Tandem folks) that we used in the 80s. Seriously?
> >
> > I've opened a discussion on the dev community list on this topic. So 
> > far, no one seems to say that you MUST use markup languages for your 
> > documentation.
> >
> > From what I see, we'd been trading off being able to do diffs in 
> > source control vs. having user-visible diffs in the documentation 
> > (via change
> > bars) and a REAL word processor. To me, the tradeoff is simple: use 
> > the real word processor.
> >
> > In addition, I think it'd be much easier to translate documents and 
> > to
> get
> > people to update them. Who wants to learn a markup language and all 
> > its intricacies. (Trust me, table handling is a royal pain and so is 
> > PDF
> > translation.)
> >
> > I want to be clear that all forms of source control diffs disappear 
> > if we move to AAO: the .odoc files are really zip archives with 
> > several files
> in
> > them. Also, we might lose the capability to provide the documents in 
> > web-page format; experimentation needed.
> >
> > What is your opinion on the matter? Would you be more willing to 
> > update documents if using AAO, which is pretty similar to working in Word.
> >
> > http://openoffice.apache.org/
> >
> > --
> > Thanks,
> >
> > Gunnar
> > *If you think you can you can, if you think you can't you're right.*
>



--
Thanks,

Gunnar
*If you think you can you can, if you think you can't you're right.*
Mime
View raw message