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:[email protected]] Sent: Friday, November 11, 2016 1:07 PM To: [email protected] 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:[email protected]] > Sent: Friday, November 11, 2016 12:54 PM > To: [email protected] > 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.*
