Commit 2a21b4d9 authored by Kristina Hoeppner's avatar Kristina Hoeppner
Browse files

Update and clean up info for documentation writers

parent fddf99bf
.. include:: /shortcuts.rstext
.. _documentation_info: .. _documentation_info:
Information for Mahara documentation writers Information for Mahara documentation writers
...@@ -7,7 +9,15 @@ This is a list in progress as I work on the documentation. There are a number of ...@@ -7,7 +9,15 @@ This is a list in progress as I work on the documentation. There are a number of
The list is not in any particular order. The list is not in any particular order.
* Screenshots are placed as figures and always include alt text and a figure description. The latter will receive numbering in the PDF export. * Screenshots
* are placed using the "figure" directive.
* always include alt text and a figure description. The latter will be numbered in the PDF export. That sets them apart from the text.
* are generally placed above a list if they are part of step-by-step instructions.
* should have as few instructions as possible about the steps that are to be taken in them. Preferably, only the step numbers so that they can be exchanged more easily and the text of the steps is translatable because it is text and not part of the image. That could also mean that translators can translate the steps but don't immediately have to change the screenshots.
* are created with Shutter in Ubuntu. It is easy to add the callouts which indicate the steps to take. However, any other screenshot software can be used. Preferably, the callouts look similarly for consistency. The color is #4C711D.
* that have callouts refer to the steps that need to be taken and that are explained below the figure.
* should only show the necessary area and not the entire screen or URL address bars etc. where not necessary.
* Admonitions in use are: * Admonitions in use are:
* note: for anything that should receive a bit more attention * note: for anything that should receive a bit more attention
...@@ -16,11 +26,9 @@ The list is not in any particular order. ...@@ -16,11 +26,9 @@ The list is not in any particular order.
* todo: for keeping a running ToDo list * todo: for keeping a running ToDo list
* Buttons such as *Save* or *Copy page* and also portfolio sections such as *Content*, *Porfolio* etc. are highlighted as emphasized text (with a single \*). * Buttons such as *Save* or *Copy page* and also portfolio sections such as *Content*, *Porfolio* etc. are highlighted as emphasized text (with a single \*).
* Little buttons can be included in the text. * Little buttons can be included in the text like |edit|, |manage|. They are added through a substitution. All replacements are kept in the file *shortcuts.rstext* which is included at the beginning of each file in which a substitution is used. They are referenced in the text as "*Edit* button |edit|" for example pointing out what the action is that you do with them.
* Screenshots of Mahara sections are not made inline, but receive the "figure" directive. They always have an alt tag and also a brief description which will show up below the image and is numbered in LaTeX PDF.
* Screenshots should have as little instructions as possible about the steps that are to be taken in them. Preferably, only the step numbers so that they can be exchanged more easily and the text of the steps is translatable because it is text and not part of the image. That could also mean that translators can translate the steps but don't immediately have to change the screenshot.
* Inline images that are refered to in the textsuch as |edit| should be included as shortcuts with the reference at the bottom of the page.
* An index entry should be created for each section. * An index entry should be created for each section.
* New features receive an index entry as well in the form "single: New in Mahara 1.5; [the thing that is new]".
* Long sections should be broken up into several pages to make the editing more manageable. * Long sections should be broken up into several pages to make the editing more manageable.
* reStructuredText does not have a set hierarchy of heading levels. They depend on the individual files. However, to be consistent, the following convention exists: * reStructuredText does not have a set hierarchy of heading levels. They depend on the individual files. However, to be consistent, the following convention exists:
...@@ -30,9 +38,3 @@ The list is not in any particular order. ...@@ -30,9 +38,3 @@ The list is not in any particular order.
* Heading 4, e.g. 1.1.1.1.: ^^^^^^^^^^^^^^^ * Heading 4, e.g. 1.1.1.1.: ^^^^^^^^^^^^^^^
* Headings below h4 should be avoided. * Headings below h4 should be avoided.
* I create screenshots with Shutter in Ubuntu. It is easy to add the callouts which indicate the steps to take. However, any other screenshot software can be used. Preferably, the callouts look similarly. The color is #4C711D.
* The callouts in the screenshots refer to the steps that need to be taken.
* Screenshots should only show the necessary area and not the entire screen or URL address bars etc. where not necessary.
.. |edit| image:: /images/buttons/edit.*
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment