Documentation revamp

As another big improvement to Ontopia comes close to being finished we want to share a sneak peek with you all.

The original idea to revamp the documentation was presented in Juni of 2015 as an enhancement to move from docbook to markdown. The main reasons for moving to markdown are:

  • Integrates better with Github by displaying markdown files as HTML, as seen here.
  • Makes the documentation source files easier to read and edit by reducing markup.
  • Removes the need for an unstable docbook plugin
  • Removes the need for Ant tasks to move files around

With the help of some automation the docbooks where converted to Markdown in march 2016. From this work it became clear that a new documentation style was required to come to an acceptable result. We’ve only recently been able to finish this part of the work. The final piece was to make sure that the distribution and all modules had the correct documentation pages and resources.

Features of the new documentation include:

  • Based on Twitter’s Bootstrap style, modified to an Ontopia color scheme
  • The documentation index is now available as a menu in every page (except javadoc)
  • Mobile device support

The near-finished code has been pushed to Github in the ‘feature/markdown’ branch pending review. The new documentation has been uploaded to a temporary location so you may preview it live:

http://ontopia.mssm.nl/doc/5.3.1/

We welcome comments and suggestions on these changes, please use the mailing list to let us know what you think of it.

Screenshots:

documentation
Documentation style
documentation-mobile
Mobile ready
Advertisements

One thought on “Documentation revamp”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s