Review Documentation

[ridoo]

The current documentation only comprises the RESTful API documentation. However, documentation about

• architecture
• development
• configuration

should also being added. When tackling this, we also should think where to add that kind of documentation and how to relate it to the associated version. Possible solutions could be

• 52North Wiki
• Maven site
• Jekyll plus Github pages
• GitHub Wiki

If you like, you can vote here on this issue

[nuest]

• NOT Maven site, that is very 2005.
• Wiki is better than Jekyll because it does not need the Jekyll infrastructure (unless Jenkins is used to build and deploy the pages)
• GitHub page of plain HTML documentation is also an alternative

What about API documentation that is integrated in the code?
I also like these guildelines: http://blog.parse.com/2012/01/11/designing-great-api-docs/

I'd also suggest to keep development documentation (imho: Wiki), configuration documentation (imho: Wiki) and API documentation (plain HTML like now is fine imo) separate because they target different user groups.

If you want versioned documentation, take a look at https://readthedocs.org/ - it uses Sphinx which is originally for Python but surely would suffice for this case as well (see also http://bronto.github.io/javasphinx/).

[ridoo]

we'll use "jekyll, kramdown, swagger" stack to build all documenation targets. As build process is done via travis and documentation sources are part of the project itself, the docs become versioned immediately.

A plus would be to keep the generated site in a webapp module, which can be overlaid by actual SPI implementations (like https://github.com/52North/dao-series-api). See also this review