Provide basic documentation

[geglock]

We should think about what and how to provide basic documentation for Eclipse Ditto.
Currently we have a small "Readme" and a "Getting started" (both as .md files).

The documentation should contain chapters about:

• scope
• architecture
• build/installation
• api
• tutorials / examples

The format of the documentation should be:

• "mainstream", so its well known in oss and everyone is simply able to contribute
• usable as source for a webpage (hosted on eclipse.org)
• powerful enough to support tables and simple maintenance of links

My proposal is to start with a list of GitHub flavored markdown files in a folder structure within "documentation" and use the GitHub repo for rendering / navigation.

[thjaeckle]

I don't think it is the best idea to go with GitHub flavored markdown.
For some background: http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
We shouldn't rush this because I doubt that we won't change the format once some documentation is public.

[marianne-klein]

I went to this year’s technical communication conference full of scepticism regarding this topic but I came back with hope.
There are people out there who already create static html out of pure md files and seem to be happy so far.

So I guess pure Markdown should suffice for the beginning.
We could stick to https://github.github.com/gfm/ and try - in a first step - to avoid the extensions as much as possible.

Thus a writer would have the possibility to easily structure his content - with headings, paragraphs, lists, examples as neutral code snippets, and to add links and pictures - without caring about the static html files created based on such files.

[thjaeckle]

Completed and published first draft to: https://www.eclipse.org/ditto/
Also set up a Jenkins (JIPP) based automation: https://ci.eclipse.org/ditto/