trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Venkat Muthuswamy <venkat.muthusw...@esgyn.com>
Subject RE: [DISCUSS] Move documentation to Apache Open Office (AOO)
Date Sun, 13 Nov 2016 04:02:39 GMT
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.*
Mime
View raw message