You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@incubator.apache.org by Gunnar Tapper <ta...@gmail.com> on 2016/11/11 07:46:04 UTC
[DISCUSS] Documentation
Hi,
Related to the muti-lingual issue but also separate since it has to do with
tools. This might be the wrong list to so please feel free to redirect.
I've created a lot of documentation for Trafodion using Asciidoc, which
allows the project to include the documentation with the source. It's OK
but also complicated when wanting to provide PDF versions of the manuals
due to font issues and other things.
Talking with other contributors, there's a clear preference to use Apache
OpenOffice for documentation. Beyond usability (and therefore more
willingness to document), it also makes translation easier.
Has anyone used OpenOffice for documentation before? If so, how is it
handled with source control etc? (OpenOffice files are really zip archives
with multiple files in them.)
Thoughts?
--
Thanks,
Gunnar
Re: [DISCUSS] Documentation
Posted by Gunnar Tapper <ta...@gmail.com>.
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 <as...@shanecurcuru.org> wrote:
> Bertrand Delacretaz wrote on 11/11/16 9:37 AM:
> > On Fri, Nov 11, 2016 at 8:46 AM, Gunnar Tapper <ta...@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.*
Re: [DISCUSS] Documentation
Posted by Shane Curcuru <as...@shanecurcuru.org>.
Bertrand Delacretaz wrote on 11/11/16 9:37 AM:
> On Fri, Nov 11, 2016 at 8:46 AM, Gunnar Tapper <ta...@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
Re: [DISCUSS] Documentation
Posted by Gunnar Tapper <ta...@gmail.com>.
For people in this particular incubator. ;)
On Nov 11, 2016 2:37 AM, "Bertrand Delacretaz" <bd...@apache.org>
wrote:
> On Fri, Nov 11, 2016 at 8:46 AM, Gunnar Tapper <ta...@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.
>
> -Bertrand
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>
>
Re: [DISCUSS] Documentation
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Fri, Nov 11, 2016 at 8:46 AM, Gunnar Tapper <ta...@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.
-Bertrand
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [DISCUSS] Documentation
Posted by toki <to...@gmail.com>.
On 11/11/2016 07:46, Gunnar Tapper wrote:
> there's a clear preference to use Apache OpenOffice for documentation.
The driving force behind that was Sun's insistence that their own dog
food be eaten.
> Beyond usability (and therefore more willingness to document), it also makes translation easier.
* Both _Anaphraseus_
(http://extensions.openoffice.org/en/project/anaphraseus) and
_Translation Tools_
(http://extensions.openoffice.org/en/project/translation-table) have
been used by documentation writers that want to stay entirely within the
AOo/OOo environment.
> Has anyone used OpenOffice for documentation before?
ODF Authors, for one.
http://www.odfauthors.org/
I'm aware of several other FLOSS & Freemium projects that use it.
> If so, how is it handled with source control etc?
Option # 1: OOoSVN, which is both unmaintained and buggy, utilizes SVN
for version control. ^1
( http://extensions.openoffice.org/en/project/ooosvn )
Option # 2: With every save, make a backup copy, and rely on cron to
rename and sweep the backups, into an archival folder.
Option # 3: Periodically make a specific save into an archive/backup
folder.
My guess is that most outfits that use AOo for documentation, use option
# 3.
^1: Considering that both SVN and AOo are Apache Projects, I'm a little
surprised that this extension is both unmaintained, and buggy.
jonathon
Re: [DISCUSS] Documentation
Posted by Gunnar Tapper <ta...@gmail.com>.
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 <to...@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.*
Re: [DISCUSS] Documentation
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Sat, Nov 12, 2016 at 8:45 PM, toki <to...@gmail.com> wrote:
> ...Five options, each of which creates a slightly different PDF...
That's (obviously ;-) only relevant if your project wants to produce
PDF documentation.
A large part of Apache projects are perfectly happy with Web-based
documentation which has much simpler typographic requirements and can
still be excellent documentation.
There's nothing wrong with docs that "look like a book" if you need
them but many projects don't have this requirement.
-Bertrand
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [DISCUSS] Documentation
Posted by toki <to...@gmail.com>.
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
Re: [DISCUSS] Documentation
Posted by Gunnar Tapper <ta...@gmail.com>.
Hi Stain,
I used different wiki technologies for documentation in a previous project.
One of the large blockers was that it was very hard to deal with versioned
documentation, especially when dealing with many different manuals. To me,
wikis work well for documentation targetted to developers that are on the
bleeding edge and simply need the latest. They don't work well for end
users that live a few releases back. (I do wish Confluence would allow raw
edit mode and WYSIWYG as it did in the past.)
I wrote the webpage in markdown because it supports raw HTML -- much better
for table handling. But, I would really have preferred to use Wordpress
since it's just superior for managing web pages... couldn't figure out how
to do that though.
For documentation, I couldn't find an easy way to do multi-chapter books,
which is why asciidoc was chosen. This is important when you have reference
manuals that hit 600-700 pages or so. Intra-document link handling gets
tricky too at that size, too.
Table handling is quite tricky in asciidoc too, especially because the PDF
converter didn't/doesn't support a lot of the different cell formats. (I
haven't looked lately.) Like you, I do like the end result with a web page
but I also have people that prefer to review/read documents on Kindle-style
devices. PDF helps with that.
But overall, my main motivation is to get others to write: make it easy to
do the right thing.
The project seems to have operated under the assumption that you can't use
tools as AOO. This discussion has helped correct that misunderstanding.
Now, we can decide on what's best moving forward.
Thanks for your help,
Gunnar
On Fri, Nov 11, 2016 at 3:14 PM, Stian Soiland-Reyes <st...@apache.org>
wrote:
> I guess primarily the answer is that your project should discuss this and
> use whatever they are comfortable with; the incubator is not forcing any
> technology. I would say that you should avoid proprietary formats (e.g.
> .docx) so that anyone can contribute.
>
> I think for developers Markdown (which is similar to AsciiDoc) edited in
> git is reasonable simple to get into, as you can generally just write text
> and then augment with !ore advanced syntax.
>
> Pull Requests via GitHub is then quite easy as the web editor has previews.
> Local editors like Atom also have live previews.
>
> The fact that it is not WYSIWYG makes it much harder to deviate from the
> common style, while a WYSIWYG-editor to me has too much freedom, documents
> would easily have all kinds of fonts and styles dancing about as different
> users edit it, unless you impose strict usage of the Heading levels etc
> rather than hitting the Bold and font size buttons.
>
> But it is obviously a barrier for non-developers to contribute, although it
> can be used by example.
>
> Like AsciiDoc, Markdown is a textual format so it is very git friendly,
> unlike the Zip archives from OO which would just give you a generic binary
> merge conflict; you would then solve it using Document Compare which is
> possible in OO, but much smoother in Microsoft Word.
>
> Apologies to OO devs, but using OpenOffice for documentation sounds to me
> like yesterday's approach, where the end target is a static PDF to print
> with blurry screenshots (shrunk to fit on A4), rather than a series of
> hyperlinked web-pages that can be continually updated and improved.
>
> So to me a wiki is often a good sweet spot for documentation, allowing
> easier editing and encouraged hyperlinked and use of images and associated
> example files. At ASF we have a Confluence install at
> https://cwiki.apache.org/ which I think has a fairly good WYSIWYG editor
> with sufficient freedoms and guidance; and the fact that it allows
> structuring pages hierarchically is a massive plus for documentation.
>
> On 11 Nov 2016 7:46 am, "Gunnar Tapper" <ta...@gmail.com> wrote:
>
> > Hi,
> >
> > Related to the muti-lingual issue but also separate since it has to do
> with
> > tools. This might be the wrong list to so please feel free to redirect.
> >
> > I've created a lot of documentation for Trafodion using Asciidoc, which
> > allows the project to include the documentation with the source. It's OK
> > but also complicated when wanting to provide PDF versions of the manuals
> > due to font issues and other things.
> >
> > Talking with other contributors, there's a clear preference to use Apache
> > OpenOffice for documentation. Beyond usability (and therefore more
> > willingness to document), it also makes translation easier.
> >
> > Has anyone used OpenOffice for documentation before? If so, how is it
> > handled with source control etc? (OpenOffice files are really zip
> archives
> > with multiple files in them.)
> >
> > Thoughts?
> >
> > --
> > Thanks,
> >
> > Gunnar
> >
>
--
Thanks,
Gunnar
*If you think you can you can, if you think you can't you're right.*
Re: [DISCUSS] Documentation
Posted by Stian Soiland-Reyes <st...@apache.org>.
I guess primarily the answer is that your project should discuss this and
use whatever they are comfortable with; the incubator is not forcing any
technology. I would say that you should avoid proprietary formats (e.g.
.docx) so that anyone can contribute.
I think for developers Markdown (which is similar to AsciiDoc) edited in
git is reasonable simple to get into, as you can generally just write text
and then augment with !ore advanced syntax.
Pull Requests via GitHub is then quite easy as the web editor has previews.
Local editors like Atom also have live previews.
The fact that it is not WYSIWYG makes it much harder to deviate from the
common style, while a WYSIWYG-editor to me has too much freedom, documents
would easily have all kinds of fonts and styles dancing about as different
users edit it, unless you impose strict usage of the Heading levels etc
rather than hitting the Bold and font size buttons.
But it is obviously a barrier for non-developers to contribute, although it
can be used by example.
Like AsciiDoc, Markdown is a textual format so it is very git friendly,
unlike the Zip archives from OO which would just give you a generic binary
merge conflict; you would then solve it using Document Compare which is
possible in OO, but much smoother in Microsoft Word.
Apologies to OO devs, but using OpenOffice for documentation sounds to me
like yesterday's approach, where the end target is a static PDF to print
with blurry screenshots (shrunk to fit on A4), rather than a series of
hyperlinked web-pages that can be continually updated and improved.
So to me a wiki is often a good sweet spot for documentation, allowing
easier editing and encouraged hyperlinked and use of images and associated
example files. At ASF we have a Confluence install at
https://cwiki.apache.org/ which I think has a fairly good WYSIWYG editor
with sufficient freedoms and guidance; and the fact that it allows
structuring pages hierarchically is a massive plus for documentation.
On 11 Nov 2016 7:46 am, "Gunnar Tapper" <ta...@gmail.com> wrote:
> Hi,
>
> Related to the muti-lingual issue but also separate since it has to do with
> tools. This might be the wrong list to so please feel free to redirect.
>
> I've created a lot of documentation for Trafodion using Asciidoc, which
> allows the project to include the documentation with the source. It's OK
> but also complicated when wanting to provide PDF versions of the manuals
> due to font issues and other things.
>
> Talking with other contributors, there's a clear preference to use Apache
> OpenOffice for documentation. Beyond usability (and therefore more
> willingness to document), it also makes translation easier.
>
> Has anyone used OpenOffice for documentation before? If so, how is it
> handled with source control etc? (OpenOffice files are really zip archives
> with multiple files in them.)
>
> Thoughts?
>
> --
> Thanks,
>
> Gunnar
>