incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From toki <>
Subject Re: [DISCUSS] Documentation
Date Sat, 12 Nov 2016 19:45:58 GMT
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.


View raw message