You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@community.apache.org by Gunnar Tapper <ta...@gmail.com> on 2016/11/11 17:57:51 UTC
[DISCUSS] Documentation
Hi,
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. We have lots
and lots of documentation (http://trafodion.apache.org/documentation.html)
and are trying to get tech writer contributors to engage, which makes word
processor support more important.
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
*If you think you can you can, if you think you can't you're right.*
Re: [DISCUSS] Documentation
Posted by sebb <se...@gmail.com>.
It's useful to be able to read commit diffs.
AIUI OpenOffice docs are zipped so diffs aren't generated by SVN/Git etc.
Also if the documentation source is all text-based then it's a lot
easier to do searches and scripted edits (e.g. to fix common typos)
On 14 November 2016 at 19:54, Manfred Moser <ma...@simpligility.com> wrote:
> I have used all those as well and my preference still sits with asciidoc. Mostly because I have a larger choice of quality output.
>
> If I have the choice overall and write more complex stuff on my own I would probably go back to LaTeX ;-)
>
> manfred
>
> Martin Desruisseaux wrote on 2016-11-14 11:16:
>
>> Le 14/11/16 à 19:10, Manfred Moser a écrit :
>>> Switching from Asciidoc to OpenOffice seems like a recipe for disaster to me.
>>> Asciidoc (or asciidoctor) is very capable for PDF creation and is used in
>>> publishing companies like OReilly.
>>
>> On my side I used at different time OpenOffice, Asciidoc, Docbook, Maven
>> APT and Markdown. After all those attempts, my preference now (for the
>> documentation that I write) is plain HTML with a CSS complete enough for
>> avoiding formatting code in most places of HTML files. I found Asciidoc
>> or Maven APT too limited (I often needed more advanced features like
>> tables with some merged cells, equations, etc). Markdown allows to write
>> HTML inline, but when I start doing that I could as well write the full
>> document in HTML and get the help of HTML editors. Docbook is very rich,
>> but requires learning a new language which is not that much simpler than
>> HTML 5.
>>
>> Another reason is for introducing some semantic in the documents.
>> Asciidoc, Maven APT or Markdown allows to said "put this text in italic"
>> while HTML 5 or Docbook allows to said "this text is a citation" or
>> "emphases this text". The rendering is the same, but I presume that the
>> value of HTML approach may slowly increase in the next years with the
>> progress of semantic web.
>>
>> Martin
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
>> For additional commands, e-mail: dev-help@community.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
> For additional commands, e-mail: dev-help@community.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org
Re: [DISCUSS] Documentation
Posted by Manfred Moser <ma...@simpligility.com>.
I have used all those as well and my preference still sits with asciidoc. Mostly because I have a larger choice of quality output.
If I have the choice overall and write more complex stuff on my own I would probably go back to LaTeX ;-)
manfred
Martin Desruisseaux wrote on 2016-11-14 11:16:
> Le 14/11/16 19:10, Manfred Moser a crit :
>> Switching from Asciidoc to OpenOffice seems like a recipe for disaster to me.
>> Asciidoc (or asciidoctor) is very capable for PDF creation and is used in
>> publishing companies like OReilly.
>
> On my side I used at different time OpenOffice, Asciidoc, Docbook, Maven
> APT and Markdown. After all those attempts, my preference now (for the
> documentation that I write) is plain HTML with a CSS complete enough for
> avoiding formatting code in most places of HTML files. I found Asciidoc
> or Maven APT too limited (I often needed more advanced features like
> tables with some merged cells, equations, etc). Markdown allows to write
> HTML inline, but when I start doing that I could as well write the full
> document in HTML and get the help of HTML editors. Docbook is very rich,
> but requires learning a new language which is not that much simpler than
> HTML 5.
>
> Another reason is for introducing some semantic in the documents.
> Asciidoc, Maven APT or Markdown allows to said "put this text in italic"
> while HTML 5 or Docbook allows to said "this text is a citation" or
> "emphases this text". The rendering is the same, but I presume that the
> value of HTML approach may slowly increase in the next years with the
> progress of semantic web.
>
> Martin
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
> For additional commands, e-mail: dev-help@community.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org
Re: [DISCUSS] Documentation
Posted by Martin Desruisseaux <ma...@geomatys.com>.
Le 14/11/16 19:10, Manfred Moser a crit :
> Switching from Asciidoc to OpenOffice seems like a recipe for disaster to me. Asciidoc (or asciidoctor) is very capable for PDF creation and is used in publishing companies like OReilly.
On my side I used at different time OpenOffice, Asciidoc, Docbook, Maven
APT and Markdown. After all those attempts, my preference now (for the
documentation that I write) is plain HTML with a CSS complete enough for
avoiding formatting code in most places of HTML files. I found Asciidoc
or Maven APT too limited (I often needed more advanced features like
tables with some merged cells, equations, etc). Markdown allows to write
HTML inline, but when I start doing that I could as well write the full
document in HTML and get the help of HTML editors. Docbook is very rich,
but requires learning a new language which is not that much simpler than
HTML 5.
Another reason is for introducing some semantic in the documents.
Asciidoc, Maven APT or Markdown allows to said "put this text in italic"
while HTML 5 or Docbook allows to said "this text is a citation" or
"emphases this text". The rendering is the same, but I presume that the
value of HTML approach may slowly increase in the next years with the
progress of semantic web.
Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org
Re: [DISCUSS] Documentation
Posted by Manfred Moser <ma...@simpligility.com>.
Switching from Asciidoc to OpenOffice seems like a recipe for disaster to me. Asciidoc (or asciidoctor) is very capable for PDF creation and is used in publishing companies like OReilly.
And as you mentioned you can use your version control system nicely. With OpenOffice you would loose the ability to do changes reviews and so on and you would basically manage binary files in your Git repo.
If OpenOffice could pick up a folder (that is the extracted zip of the file format) and you could version control that the situation would be different, but from all I know that is not possible. Maybe you could hack something together that does that though. Like some sort of ignore file for the binaries and a build script that unzips the doc file and then the writer would commit those.
Manfred
Gunnar Tapper wrote on 2016-11-11 09:57:
> Hi,
>
> 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. We have lots
> and lots of documentation (http://trafodion.apache.org/documentation.html)
> and are trying to get tech writer contributors to engage, which makes word
> processor support more important.
>
> 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
> *If you think you can you can, if you think you can't you're right.*
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org