[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
Re: [iot-pmc] Eclipse Kura Documentation
|
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?
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