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.*
|