Writing Style

Style-guide

• "shell commands" should be in reST style for commands, also in written text
• make sure of glossary use
• topic descriptions ?
• header always with Capital letter for every first letter in every word
• links should be "in text" and not in the footer
• "write out acronyms, meaning if you write ttw do it like ttw (trough the web) for teh first time you use it in a document.
• Do not use tabs !
• Do not check docs against pep8, flake8, etc

Naming Convention

Writing is not coding !

Directories

Please use - and not _ for naming folder

Bad: mastering_plone

Good: mastering-plone

Underscores are only used for templates like _templates and for static directories like _static.

This is also good to see the difference between written content and template file and such stuff

Index

:About: Deploying Plone with Ansible and OpsWorks
:Level: All levels

Add this always to the index.rst of a training, of course you will need to adjust it, according to the training.

Levels

We use two different ones

• All levels = suited for everyone
• Experienced = 'only' for people with Plone programming knowledge

**This needs to go into /about, too **

If you use

 py:mod

Please make sure the mod you want to include is configured in Sphinx, otherwise it will not work !

Includes

Using

..include::

is most of the time not cool, be really careful with this !

Reasons

• different tone of voice
• different writing style
• possible different audience
• possible different reST style
• multiple reference-labels (same ones), which will result in build errors
• no control of the included file as in changes