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 Mon, 14 Nov 2016 02:03:31 GMT
Hi Jonathon,

Thanks for the great information! I'll definitely look into supporting ePub
and Mobi formats as well as thinking through if the process can be
improved.

As for multi-book, I fell in love with it back when using FrameMaker. A
word processor supporting emacs commands can never be wrong. :)

Thanks,

Gunnar



On Sat, Nov 12, 2016 at 12:45 PM, toki <toki.kantoor@gmail.com> wrote:

> On 12/11/2016 04:09, Gunnar Tapper wrote:
>
> > For documentation, I couldn't find an easy way to do multi-chapter books,
>
> If AOo is meant, use Master Documents.
> There are a couple of use cases  (^1 ), where Master Documents don't
> work. In those instances, virtually every solution will fail. (^2)
>
> > but I also have people that prefer to review/read documents on
> Kindle-style devices. PDF helps with that.
>
> Most eBook readers, and smart phones do not handle PDFs very well. For
> those, either ePub or Mobi work much better.
>
> > But overall, my main motivation is to get others to write:
>
> Writing good documentation is a long, arduous process. It involves
> explaining the various options, including when and how to use them.
> Options that the individual writing the documentation might not be aware
> of.
>
> Taking a trivial example:
> * Export PDF;
> * Export as PDF;
> * Print (to PDF);
> * Print (as PDF);
> * Send Email as PDF;
> Five options, each of which creates a slightly different PDF.
> Easy to explain, with blatantly obvious differences.
>
> For a slightly harder example to explain, look at ligatures in English,
> using the Latin Writing System. Yes, it works, but the results are much
> better when both CTL and Asian text support is turned on.
>
> For something that is not only not obvious, but incredibly difficult to
> track down, the presence or absence of metadata in the fonts that are
> used, affects whether or not AOo utilizes the font correctly. (That you
> paid US$10,000 for the typeface, does not mean that the metadata is
> either present, or accurate. Nor does the fact that the typeface was
> gratis, mean that the metadata is either absent, or inaccurate.)
>
> > make it easy to do the right thing.
>
> This is where a defined work flow process is vital.
>
> For various reasons, the workflow used back when Sun was running OOo,
> weren't acceptable here (Apache Foundation running AOo).
>
> So what happens is that would-be documentation creators sink, due to a
> lack of either clear guidelines, or a pre-defined workflow process.
>
>
> ^1: The most commonly encountered such use case, is when different
> audiences have to get different content, but that content differs by
> anything between a word, to three or four paragraphs.
>
> ^2: For the most commonly encountered use case, LeanPub offers the only
> easy to implement solution that works. The issue with that solution, is
> that one's content is no longer confidential, which is the usual reason
> for having slightly different content for different audiences.
>
> jonathon
>
>


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