incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gunnar Tapper <tapper.gun...@gmail.com>
Subject Re: [DISCUSS] Documentation
Date Fri, 11 Nov 2016 17:53:53 GMT
Thanks Shane.

I started my career with (MUCH OLDER) markup languages in text editors
where you had special tags for change bars etc.

I agree that source control help diffs for developer while word processors
provide easy ways to show diffs to the user. Wearing my UX hat, I optimize
for users and making it easy for people to document, spell check, grammar
check, translate, etc. Different strokes for different folks.

It wasn't straight forward to figure out how to set up a system for
asciidoc with PDF but that's been done. But, as mentioned, I see an
unwillingness to help contribute, especially from people with tech writing
skills.

I will ask the dev community what they do with AOO, if at all. Thanks for
the pointer.

Gunnar

On Fri, Nov 11, 2016 at 2:51 AM, Shane Curcuru <asf@shanecurcuru.org> wrote:

> Bertrand Delacretaz wrote on 11/11/16 9:37 AM:
> > On Fri, Nov 11, 2016 at 8:46 AM, Gunnar Tapper <tapper.gunnar@gmail.com>
> wrote:
> >> ...Talking with other contributors, there's a clear preference to use
> Apache
> >> OpenOffice for documentation....
> >
> > *for some people*, right? I think many of us are big fans of creating
> > documentation using structured text in version control repositories.
>
> Yes, using AOO is very hard on version control, since it's normally
> stored as a blob not a diff.
>
> There are many different structured documentation tools in various
> projects at Apache, and both PDFBox, Cocoon, and Forrest (and probably
> others) can be used to translate various kinds of structured docs
> (asciitext, markdown, xml, whatever) into PDFs for reading if desired.
>
> From the peanut gallery, I'd suggest researching some of the other doc
> tools in use at Apache projects - perhaps ask on
> dev@community.apache.org as well for ideas.  But in the end, the
> decision is up to whoever's actually writing the docs *for that
> project*.  If your contributors really will prefer AOO over other tools,
> then use that.
>
> - Shane
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>
>


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