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.gun...@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 >
