.. comment
	
	all inline tags to start with _help_rules_
	
.. index:: How to; Rules for editing pages


.. _help_rules_top:


Rules for editing pages
#######################

.. include:: /pages/common/pageunderconstruction.txt
	:start-line: 3
	
	
.. contents:: Contents:
		:local:
		:depth: 1
		:backlinks: top
		
**************		
Page content
**************

* After the title, the file includes the common text. ::

	.. include:: /pages/common/pageunderconstruction.txt
		:start-line: 3
		
* The page starts with a **contents** (see :ref:`help_rules_contents`). These are also included for each significant section. This provides a "what you are going to see", and takes no maintenance.
* Top of the page has a very **light weight introduction** that includes an overall picture with the location of the section indicated. The overall picture should be common (except for the highlights) across all the similar pages (e.g. same pic for AAM, ADPM, ADM, CTC, ParaMapping, AIM ARM…)
* If necessary the next item is **prerequisites**, this could be links to other pages.
* Ideallly the first item in a detail section is a **video**. These can be local or remote (e.g. youtube)
* Subsequent sections do **step-by-step** using (if logical) screen grabs from the video
* Use **todo** sections for areas that have been identified as needed, or quick notes on the steps that have yet to be written up properly.::

	.. todo::

		the text, images etc that are work in progress


***********
Navigation	
***********

* Use **Short titles** so can understand at a glance without having to read the text i.e. if page titles are long, then override in the index
* Have no more then 10 or 12 items at any level as the eye cannot quickly scan/locate with more than this.

.. figure:: /images/help/help_editnav01.png 
	:scale: 100 %
  
	Illustration of good and bad navigation

.. _help_rules_contents:

*********
Contents
*********

The contents listing makes it easier to navigate up/down and also makes the RDT tree synchronise.

* The contents should include backlinks.
* It is prefereable to have a local contents at each significant section.
* There is no rule for the depth but the preference is 1.

::

	.. contents:: Contents:
		:local:
		:depth: 1
		:backlinks: top
	
*****************
Inline references
*****************

* The pages have a naming convention for the inline references (e.g. _how_DM_xxx) for (ease of maintenance);
* These should be used (:ref:) instead of :doc: references, so that pages can be moved, renamed, split, consolidated without impacting other pages;
* The top of page has top inline reference e.g. _how_DM_top. The build checks this is not used on other pages;

**************
Index entries
**************

* An index reference shall be added at the top of each page. The above example adds a “pair” of references for the page::

	.. index:: :pair Domain Model; How To

* This means the index can be used to find all the “How To” pages, and find all the pages wrt “Domain Model”
* Other options see http://www.sphinx-doc.org/en/stable/markup/misc.html
	* E.g. in text
	* E.g. for subheadings such as \.. index:: :pair Domain Model; Constraints
* Note: “index:: :pair” is not always the best. Consideration should be taken over the collections in the index. The below files under “Activity Model” and “Mapping”, but not reciprocal entries::

	.. index:: Activity Model; How to Map to Data Planning Model
	.. index:: Mapping; How to - Activity Model to Data Planning Model

.. figure:: /images/help/help_editindex01.png 
	:scale: 100 %
  
	Illustration of result of the above paired index entries

************************
Images naming convention
************************

The image name should include a shortened form of the location of the page, and the page itself (e.g. ht_aam_xxx.png). This prevents accidental overwrite.
	

**********
Videos
**********

* Include an index so all the videos can easily be located
* Add a subheading so appears in contents
* Record the video 1280x720 (widescreen 16:9) as this is then stored as HD in youtube
* Copy the youtube Share:Embedded as raw:: html	


.. figure:: /images/help/help_editvideo01.png 
	:scale: 100 %
  
	What to copy from youtube

::

	.. index:: Video; How to use a constraint in mapping

	^^^^^
	Video
	^^^^^

	.. raw:: html

		<iframe width="560" height="315" src="https://www.youtube.xxxx" frameborder="0" gesture="media" allowfullscreen></iframe>

.. _help_rules_keywords:
		
*********
Keywords
*********

There is a file in the source folder called **keywords.rst**. This contains key text that is replaced at build time.
It is included at the end of each file.::

	.. include:: /keywords.rst 

This contains:

* External references (make easer to maintain as all in one place) e.g. ::

	.. |OMG SysML 1.4| replace:: `OMG Systems Modeling Language (OMG SysML) Version 1.4 <https://www.omg.org/spec/SysML/1.4/PDF>`__
	
* Author names/emails (ease of maintenance e.g. when general support email changes) e.g. ::

	.. |Judith Crockford| replace:: `Judith Crockford (AP243) <mailto:judith.crockford@airbus.com?subject=STEPLib Documentation>`__
	
* Links to other Sphinx doc (we do not use the `intersphinx <http://www.sphinx-doc.org/en/stable/ext/intersphinx.html>`_ capability because contributors environments may be different ::

	.. |Git Index| replace:: `Git Documentation Index <http://cvs.boost-lab.net/sphinx/Git_Gitlab_User_Guide/html/index.html>`__
	
* short cut names e.g. |AAM| ::

	.. |AAM| replace:: Application Activity Model

********	
Glossary
********

* The glossary is stored in the source/glossary.rst 

* Each term has an entry with the term, definition and links to major sections of the guide::

	ADM
	DM
		Application Domain Model
		
		See :doc:`Overview</pages/TheModelsOfTheStepArchitecture>`
		
		See :doc:`Description</pages/TheApplicationDomainModelOfAnAP>`
		
		See :doc:`How To</pages/howto/howtoDomainModel>`
		
* The glossary is at the end of the table of contents before the index. 
* Glossary terms are automatically added to index
* Glossary terms are used in the text with the **:term:`xxx`**  ::

	... defined in anyAP, with connected :term:`AAM`, :term:`ADPM`, :term:`ADM` and ...

.. figure:: /images/help/help_editgloss01.png 
	:scale: 100 %
  
	What to copy from youtube

**************
Section Author
**************

At a minimum each page should have a section author at the end using the keywords::

	.. sectionauthor:: |Judith Crockford|
	
Section authors can also be added for each heading/subheading when there are more than one author per page.

**********************
Duplication of content
**********************

There are cases it is more readable to duplicate content in multiple places rather than use hyperlinks. 

* To ease maintenance, this content should be stored in a separate text file and included. 

* The file should be .txt rather than .rst so that it is ignored as a file by the parser. 

* The file can contain content at the beginning which can then be ignored. ::

	.. include:: /pages/common/pageunderconstruction.txt
		:start-line: 3
		
		
.. _help_rules_img:

******************
Figures and images
******************

All images should specify a scale, even if it is 100%. This automatically adds a click to open the image – and the M-R options of New Tab and New Window.

::

	.. figure:: /images/common/comingsoon.png
		:scale: 100%
    
		Figure description



.. sectionauthor:: |Judith Crockford|

.. include:: /keywords.rst