trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Varnau <>
Subject RE: [DISCUSS] Move documentation to Apache Open Office (AOO)
Date Fri, 11 Nov 2016 21:07:24 GMT
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

Likewise, how do reviewers see the deltas easily in the review process.


> -----Original Message-----
> From: Gunnar Tapper []
> Sent: Friday, November 11, 2016 12:54 PM
> To:
> 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.
> --
> Thanks,
> Gunnar
> *If you think you can you can, if you think you can't you're right.*
View raw message