Re: [iot-wg] documentation example

[Jens Reimann <jreimann@xxxxxxxxxx>]

Hi,

that it was not possible to host such a documentation outside of readme.io.

Do I understand it right, that not even the „sources“ of the documentation are on Github, but only maintained at readme.io? If so, that would also be a no-go for me.

No, what I meant was: readme.io is rendering the documentation, as a service. However you cannot replicate that process outside of readme.io in the same way.

On the other hand I wasn't able to actually find the Eclipse Che documentation. Surely it must be somewhere, and I it was just me. But having a look at readme.io and trying to find out how it works is kind of tricky. It seems you can't even find some sort of documentation unless you start a 14 days trial.

I do think it is a fine tool. Just not the right one for open source projects.

Right now every Eclipse project does have a static homepage available (with some sort of PHP), stored in a Git repository. Wouldn't it be an idea to extend this approach with some sort of page rendering pipeline? So that you check in your documentation to that Git repository and the rendering pipeline rebuilds that homepage and hosts it. There are a few rending pipelines available, such as AsciiDoc, Jekyll, … which could do the task. Maybe even create a domain "docs.eclipse.org" where this all happens.

I think most documentations setups are split up: 1) content storage, 2) rendering pipeline, 3) hosting

1) Should be Git repositories, Hosted at Eclipse (or Eclipse GitHub) IMHO

3) Could be Eclipse infrastructure, but it should be possible to easily host this outside of Eclipse

And 2) is probably the tricky part ;-)

What Kura currently does seems like the right approach to me. Hosting content at their GitHub repository, using jekyill to render, hosting on github.io. But you could also just host is somewhere else. The content format is Markdown, which every GitHub user knows. You can fully customize the theming, but keep it separate of the content. So this can be re-used as well.

So what do you think is missing or could be improved?

Cheers

Jens

--

Jens Reimann
Senior Software Engineer / EMEA ENG Middleware
Werner-von-Siemens-Ring 14
85630 Grasbrunn
Germany
phone: +49 89 2050 71286
_____________________________________________________________________________

Red Hat GmbH, www.de.redhat.com,
Registered seat: Grasbrunn, Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Paul Argiry, Charles Cachera, Michael Cunningham, Michael O'Neill