incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stian Soiland-Reyes <st...@apache.org>
Subject Re: [DISCUSS] Documentation
Date Fri, 11 Nov 2016 22:14:02 GMT
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" <tapper.gunnar@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
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message