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" <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 > > > -- Thanks, Gunnar *If you think you can you can, if you think you can't you're right.*
