Re: [DISCUSS] Documentation
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, tokiwrote: > 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
On Sat, Nov 12, 2016 at 8:45 PM, tokiwrote: > ...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-unsubscr...@incubator.apache.org For additional commands, e-mail: general-h...@incubator.apache.org
Re: [DISCUSS] Documentation
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 signature.asc Description: OpenPGP digital signature
Re: [DISCUSS] Documentation
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 signature.asc Description: OpenPGP digital signature
Re: [DISCUSS] Documentation
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-Reyeswrote: > 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" 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
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"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 >
Re: [DISCUSS] Documentation
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 Curcuruwrote: > Bertrand Delacretaz wrote on 11/11/16 9:37 AM: > > On Fri, Nov 11, 2016 at 8:46 AM, Gunnar Tapper > 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 > d...@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-unsubscr...@incubator.apache.org > For additional commands, e-mail: general-h...@incubator.apache.org > > -- Thanks, Gunnar *If you think you can you can, if you think you can't you're right.*
Re: [DISCUSS] Documentation
For people in this particular incubator. ;) On Nov 11, 2016 2:37 AM, "Bertrand Delacretaz"wrote: > On Fri, Nov 11, 2016 at 8:46 AM, Gunnar Tapper > 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-unsubscr...@incubator.apache.org > For additional commands, e-mail: general-h...@incubator.apache.org > >
Re: [DISCUSS] Documentation
Bertrand Delacretaz wrote on 11/11/16 9:37 AM: > On Fri, Nov 11, 2016 at 8:46 AM, Gunnar Tapper> 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 d...@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-unsubscr...@incubator.apache.org For additional commands, e-mail: general-h...@incubator.apache.org
Re: [DISCUSS] Documentation
On Fri, Nov 11, 2016 at 8:46 AM, Gunnar Tapperwrote: > ...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-unsubscr...@incubator.apache.org For additional commands, e-mail: general-h...@incubator.apache.org
[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