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 Sun, 13 Nov 2016 18:49:56 GMT
Here's where I'm coming from:

1. Recently, I was approached by a colleague that wanted to contribute some
documentation changes. I explained how you have to set up a build
environment, download the source, learn asciidoc, build the documentation,
etc. The result: an e-mail with the proposed changes. The y barrier for
non-developer contribution is way to high.
2. With a few exceptions, I don't see much of review of documentation. I
see even less contribution. It's worse than I've seen in project that use
word processors and a simpler review process.
3. Any user experience material has to be seen in context. Diff
documentation works OK for code but not for UIs, documentation, etc.
4. I recently reorganized and amended the Client Install Guide. A job that
should have taken a few hours took way more time. There are a few other
guides that would benefit from a similar exercise but I'm unlikely to
pursue the needed changes because of how arduous the task is.
5. We should translate the documentation to Chinese. We had the possibility
to get tech writers involved. Without word processor, it's not happening.

Gunnar

On Sat, Nov 12, 2016 at 9:02 PM, Venkat Muthuswamy <
venkat.muthuswamy@esgyn.com> wrote:

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



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