trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gunnar Tapper <tapper.gun...@gmail.com>
Subject Re: [DISCUSS] Move documentation to Apache Open Office (AOO)
Date Fri, 11 Nov 2016 21:13:20 GMT
No different from working in Word as far as I can tell: merge changes into
a single document. Open the document and jump to next change for review.

In other words: the same process used for all design and user documentation
before donating Trafodion to Apache. And every other project I ever worked
on since the mid 80s. :)

Gunnar

On Fri, Nov 11, 2016 at 2:07 PM, Steve Varnau <steve.varnau@esgyn.com>
wrote:

> 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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message