Writing Documentation

The Kolab community has a reference implementation of its releases, which can best be described as a next-next-finish installation [1] of a single node [2] running Enterprise Linux 7 [3].

For writing documentation, this means that all documented commands and file paths mentioned need to match that specific implementation [4] of Kolab installed on Enterprise Linux 7, and that every HOWTO needs to start at the aforementioned null situation.

This sounds harsh, and it probably is, but here’s how you can work with it:

• When you create a HOWTO for something on Debian, your HOWTO should probably be titled: HOWTO: Achieve Greatness (on Debian Wheezy).

• When you do write a generic HOWTO, you can re-iterate the commands issued for different distributions:

  After changing the configuration, restart the service:
  
  .. parsed-literal::
  
      # :command:`systemctl restart postfix`
  
  On Debian Wheezy, execute the following instead:
  
  .. parsed-literal::
  
      # :command:`/etc/init.d/postfix restart`
  

Footnotes

[1]

This means to confirm the default settings (other than perhaps the passwords) during Kolab Groupware Setup, including but not limited to the characters used in the passwords chosen – while we have learned of issues when using passwords with special characters, which relate to third party application defaults.

[2]

A single node is a single operating system instance; physical, virtual, docked or contained.

[3]

In the family of Enterprise Linux 7 distributions that we provide packages for are Red Hat Enterprise Linux and CentOS.

[4]

The specific implementation is a single-node deployment topology.