Decide on how to create User Documentation, and set up Infrastructure

[jastram]

The toolchain must include user documentation, for various reasons. An infrastructure for this must be created.

I found the management of documentation in a wiki useful, which is automatically included in the form of Eclipse Help into the product by the CI system (we do this for RMF, see http://eclipse.org/rmf/pror/)

For sophisticated documentation, it is possible to use Latex to generate a handbook, online help and Eclipse help at the same time (we do this with Rodin, see http://handbook.event-b.org/)

These are just two possibilities. Once we decide on one, we can independently delegate the creation of documentation.

Requirements

1. The solution shall generate PDF and Eclipse Help
2. The documentation must be available as HTML as well
3. The Eclipse Help shall support context sensitive Help

[cecilebraun]

I think for the components the wiki is a good approach since almost the eclipse existing plug-in have one.
For the complete openETCS tool chain we should produce a handbook together with the developer guidelines.

[jastram]

Izaskun will do this. We'll assign her to this issue, as soon as she is part of the toolchain project.

Todo List:

• Creating a Design Spec for the Documentation Infrastructure
• Recruiting representatives of the Stakeholders
• Make an appropriate technology choice
• Implement the chosen technology
• Create a skeleton for the documentation

Izaskun will give an update on the progress on Dec.3 or Dec. 5

[MERCEmentre]

I am also in favor of Wiki page for doc generation, it is much easier to update the documentation (tested and approved with ProR).

Opened questions:

• Can we use GitHub wiki to do that?
• What are limitations of such approach (obviously, only basic formatting can be used). What about images? Tables?

[MERCEmentre]

Started creating wiki pages for documentation, starting from: https://github.com/openETCS/toolchain/wiki/Documentation

[jastram]

@MERCEmentre thanks for getting this started.

Can we use GitHub wiki to do that?

I don't know. We use WikiText for the ProR documentation. The FAQ does not explicitly mention gitHub (which does not mean much).

My suggestion: Try to get WikiText to work locally first and check the configuration into the toolchain repository as a new Eclipse plug-in. You can use ProR's WikiText plugin as a starting point. We should separate the issue of content writing and automated content processing. Once the content processing works, we now what constraints we have with respect to content creation.

What are limitations of such approach?

I think all web content is supported, considering that Eclipse Help is just HTML. Images should be fine.

[jastram]

@idelatorre @MERCEmentre : Stefan ( @srieger ) will help driving this. In a nutshell, it is still not clear whether the power of Latex is required or not, which has a direct impact on the technology choice. Please try to resolve this this week, so that we can start on creating the generation scripts next week).

[MERCEmentre]

Thanks @jastram for all the pointers. Wiki approach seems fine to me for now so I think we should start with it.

[MERCEmentre]

It is easy to get Markdown version of a wiki page, e.g. https://raw.github.com/wiki/openETCS/toolchain/openETCS-Welcome-Screen.md

[MERCEmentre]

Markdown seems to be supported into Mylyn (at least in Nightly Build version): https://bugs.eclipse.org/bugs/show_bug.cgi?id=329528

[JonasHelming]

@jastram : Is the help from the wiki really supposed to be transformed into the Eclipse specific format? Wouldn't it also be sufficient to display the online help in a browser within Eclipse?

[jastram]

@JonasHelming - the transformation to Eclipse Help is definitely a "nice to have". Nevertheless, besides Eclipse Help, there was discussion on generating a PDF from the documentation as well.

At a minimum, we need some structure that goes beyond the structure of a Wiki (essentially, a hierarchical TOC). Using some of the technologies mentioned here would provide such a structure, with the side benefit of an integrated Eclipse Help System (and maybe later automatic PDF generation).

But ultimately, @idelatorre is the expert on these questions. I suggest that you talk to her to find a solution that is as complex as necessary, but as simple as possible.

[JonasHelming]

@idelatorre : As we discussed today, this issue is pretty urgent. What is your current state?