Differential D89 Diff 198 source/contributor-guide/documentation/writing-documentation.rst

Changeset View

Standalone View

source/contributor-guide/documentation/writing-documentation.rst

This file was added.

				.. _dev-writing-documentation:

				=====================
				Writing Documentation
				=====================

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

				For writing documentation, this means that all documented commands and
				file paths mentioned need to match that specific implementation [#]_ 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`

				.. rubric:: Footnotes

				.. [#]

				This means to confirm the default settings (other than perhaps the
				passwords) during :ref:`installation-guide-setup-kolab`, 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.

				.. [#]

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

				.. [#]

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

				.. [#]

				The specific implementation is a single-node deployment topology.