docs for users

docs/arkestra_for_users/entities.rst

@@ -0,0 +1,142 @@
+#######################
+Entities
+#######################  
+
+**************************************************
+What exactly is an entity?
+**************************************************
+An *entity* could be:
+
+an organisation:
+	*Cardiff University School of Medicine*
+a part of a larger organisation:
+	*Institute of Infection & Immunity*
+	*Research Office*
+a group of other entities:
+	*Research institutes*

+	*Administrative & support offices*
+a collection of people:
+	*Web editors*
+	*School IT liaison officers*
+
+Entities exist in a *hierarchy*:
+
+*	Cardiff University
+
+	*	Cardiff University School of Medicine
+
+		*	Institutes
+
+			*	Institute of Infection & Immunity	 
+			*	Institute of Cancer Genetics
+			*	Institute of Medical Education
+
+				*	Admissions
+				*	Assessments
+		*	Administrative offices
+
+			*	Finance
+			*	Personnel
+
+**************************************************
+Managing entities
+**************************************************
+
+Let's start by getting to work on an entity.
+
+The Entities change list
+************************
+
+In the Arkestra admin site, find `Contacts & people` > `Entities`. They are arranged in a tree reflecting the hierarchy of entities.
+
+.. figure:: entity-change-list.png 
+   :width: 100%
+   :alt: map to buried treasure
+
+   The **Entities** change list
+
+You can:
+
+* **search** the list of Entities
+* **filter** the list according to various criteria
+* **expand and collapse** sections of the hiearchy using the controls in the window
+* **move** entites by dragging them around within the tree
+
+Either select an existing entity to edit, or create a new one if none exist.    
+
+Editing an entity
+*****************
+
+.. figure:: entity-change-view.png 
+   :width: 100%
+   :alt: map to buried treasure
+
+   The **Entity** change view - you'll find many of the same controls and
+   features throughout Arkestra's adminstration interface.
+
+This is where we tell Arkestra what it needs to know about our entity.
+
+Basic information
+=================
+
+Name   
+	its official title, in full
+
+Short name for menus
+	a shorter version, if required
+
+Image 
+	an image (for example a logo)
+
+Home page
+	The entity will likely have a number of pages associated with it in the
+	**Pages** system that; select the root page of that section. Arkestra will
+	know that *all* the pages in that section belong to this entity.
+
+Parent
+	The entity's parent in the hierarchy. You can also change this by dragging the entity around in the change list, but if the hierarchy contains hundreds of items, this is a more efficient way to do it.
+
+Include parent entity's name in address
+	Arkestra builds an entity's address automatically, and will include its parent's name in that automatically. Usually that makes sense (*IT Office, School of Medicine*, but sometimes it might look silly (*Cardiff University School of Medicine, Cardiff University*), so this allows us to turn it off.
+
+Abstract
+	Some entities are actual organisational entities, like the University or the Research Office. Others are just useful groupings, or *abstract entities*.   
+
+Location
+========
+
+Address
+	This is there to show you how Arkestra will render the entity's address       
+
+Building
+	where the entity is based
+
+Building recapitulates entity name
+	Sometimes, the building name and the entity name are so similar it would be silly to have them both in the address. If so, this field allows Arkestra to know that it shouldn't include them both in addresses
+
+Precise location
+	the place *inside* the building - floor, room number, etc
+
+Precise location
+	any note for potential visitors 
+
+Contact
+========     
+
+Email address
+	if the entity has its own email address
+
+Phone contacts
+	choose or add a suitable label; don't try to format numbers
+
+Contacts & people, News & Events, Vacancies & Studentships
+==========================================================
+
+Arkestra will publish pages of various types automatically if required. The controls are very similar for them all, and also for other modules that might be added by other applications, and will look much like:
+
+Publish a contacts and people page for this entity automatically 
+   if this entity should have its own contacts and people page
+
+Title
+	what the page should be called
+

docs/arkestra_for_users/introduction.rst

@@ -0,0 +1,75 @@
+#######################
+The concept of Arkestra
+#######################  
+
+Arkestra was conceived as an answer to the problem: **what is the best way for
+an organisation to publish information on the web?**
+
+**************************************************
+The shortcomings of web content management systems
+**************************************************
+
+Users of web content management systems will know that generally speaking,
+they don't work well, especially when organisations use them, and the bigger
+the organisation and the site, the worse the problems.
+
+Web content management systems waste users' time, and their work, and produce
+sites full of inconsistent content, inconsistently presented.
+
+They don't offer users enough freedom to do what they need, and they offer too
+much, so they can do things they shouldn't - both at the same time.
+
+Arkestra is an attempt to avoid these pitfalls, by taking a different
+approach.
+
+**************************************************
+Arkestra's approach
+**************************************************
+
+Arkestra models the real world, building meaningful real-world relationships
+into its structures.
+
+It's a *semantic publishing system* rather than a *content management system*;
+it handles meaningful information, rather than mere content or data, and makes
+as much use as possible of this information as possible.
+
+Arkestra has been designed around a single key imperative: **don't waste
+people’s time.**
+
+Wherever possible, Arkestra should:
+
+* make it easy to capture and manage useful information
+* make the information easily re-usable
+* re-use it automatically and appropriately whenever possible 
+
+**************************************************
+Arkestra's model of the world
+**************************************************
+
+Arkestra begins by modelling the basic concept of an organisation. An organisation - an **Entity** in Arkestra's terminology - might:
+
+* contain other sub-entities within it 
+* occupy a number of buildings across different sites
+* have people who have various different roles in it, and engage in different
+  activities
+* hold events of various kinds
+* need to publish news about its activities
+
+... amongst numerous other things.
+
+Arkestra models all of these, and their relationships to each other.
+
+If an entity is a based in a certain building, and that building has a postal
+address, Arkestra can work out the correct postal address for the entity. If a
+person works in that entity, Arkestra can infer the person's address.
+
+If a particular set of web pages is associated with a particular entity, then
+Arkestra will be able to associate other relevant things with those pages -
+people, events, news and so on - automatically.
+
+These things can will also be associated with each other in various important
+ways in the real world: an event might feature particular people, and take
+place at a particular date and time, in a particular location; Arkestra models
+and makes use of these relationships too.
+
+The next section will examine entities more closely.

docs/index.rst

@@ -31,19 +31,30 @@ Getting started
    getting_started/starting_your_own_project
 
 **************
-Using Arkestra
+Arkestra for users
 **************
 
 .. toctree::
    :maxdepth: 2
 
-   using_arkestra/templates
-   using_arkestra/using_news_and_events
-   using_arkestra/image_sizing_system
-   using_arkestra/links_system
-   using_arkestra/video_system
-   using_arkestra/arkestra_generic_models
-   using_arkestra/migration
+   arkestra_for_users/introduction
+   arkestra_for_users/entities
+
+
+**************
+How it works
+**************
+
+.. toctree::
+   :maxdepth: 2
+
+   how_it_works/templates
+   how_it_works/using_news_and_events
+   how_it_works/image_sizing_system
+   how_it_works/links_system
+   how_it_works/video_system
+   how_it_works/arkestra_generic_models
+   how_it_works/migration
 
 Indices and tables
 ==================