Re: [iot-pmc] Eclipse Kura Documentation

[Jens Reimann <jens.reimann@xxxxxxxxxxxxxxx>]

Hello David,

I do know that the following suggestion sounds quite "old-school", totally un-hipster and way too 90ies ...

But I did find to use Docbook 5 (XML) quite useful. There are lots of pros and cons. But the biggest advantage is that you have the "source code" of your documentation in a well defined format and can generate readable documents use various technologies. Even without a service in the cloud.

I really admit that writing documentation in XML is far from user friendly ;-) Markdown, APT, et al ... are all way easier to understand. For a single page or two. But I guess Kura does need a few "pages" more. Docbook has things like proper cross referencing which come in handy when looking at a bigger documentation.

You will need a few scripts around that when building the documentation. But there are a few Java based tools like the Maven based "Docbkx Tools" [1] and the "Maven jDocBook" plugin [2], which make the transformation from XML to PDF, HTML a lot easier.

You can have a look at an example here [3]. We also do generate documentation based on system properties and EMF models, with a little bit of XSL processing and Java help.

So unless you already have scorched earth by Docbook, give it a though.

Jens

[1] http://docbkx-tools.sourceforge.net/
[2] http://maven-jdocbook-plugin.jboss.org/
[3] https://github.com/ctron/eclipse_scada_book

On 04/30/2016 10:39 AM, Woodard, David wrote:

Hello,

The Eclipse Kura team is looking at better ways to handle documentation. We are currently using Github IO, but would like to move to something that provides more management features for committers and a better experience for users. We are considering Read the Docs [1], but would like to ask the following questions:

1. Is the Eclipse Foundation okay with us hosting documentation on this site?

2. Do other projects have documentation solutions that they have found useful?

[1] https://readthedocs.org/

Thanks,

David Woodard

Eclipse Kura Project Lead

_______________________________________________
iot-pmc mailing list
iot-pmc@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/iot-pmc

-- 
IBH SYSTEMS GmbH
D-85235 Pfaffenhofen an der Glonn
Läutenring 43
Geschäftsführer / CEO: Dr. Thomas Heitzig

Amtsgericht München
Handelsregister Nummer  HRB 197959
USt ID: DE267945175

Office Munich
D 80992 München
Agnes-Pockels-Bogen 1
T +49 89 18 9 17 49 0

The information transmitted is intended only for the person or entity
to which it is addressed and may contain confidential and/or pivileged
material. Any review, retransmission, dissemination or other use of,
or taking of any action in reliance upon, this information by persons
or entities other than the intended recipient is prohibited. If you
received this in error, please contact the sender and delete the
material from any computer.

Attachment: signature.asc
Description: OpenPGP digital signature