Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

docs for users #84

Merged
merged 1 commit into from

1 participant

@evildmp
Owner

No description provided.

@evildmp evildmp merged commit a277fe9 into develop
@evildmp evildmp deleted the user-docs branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 23, 2013
  1. docs for users

    authored
This page is out of date. Refresh to see the latest.
View
142 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
+
View
BIN  docs/arkestra_for_users/entity-change-list.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  docs/arkestra_for_users/entity-change-view.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
75 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.
View
0  ...sing_arkestra/arkestra_generic_models.rst → .../how_it_works/arkestra_generic_models.rst
File renamed without changes
View
0  docs/using_arkestra/image_sizing_system.rst → docs/how_it_works/image_sizing_system.rst
File renamed without changes
View
0  docs/using_arkestra/links_system.rst → docs/how_it_works/links_system.rst
File renamed without changes
View
0  docs/using_arkestra/migration.rst → docs/how_it_works/migration.rst
File renamed without changes
View
0  docs/using_arkestra/templates.rst → docs/how_it_works/templates.rst
File renamed without changes
View
0  .../using_arkestra/using_news_and_events.rst → docs/how_it_works/using_news_and_events.rst
File renamed without changes
View
0  docs/using_arkestra/video_system.rst → docs/how_it_works/video_system.rst
File renamed without changes
View
27 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
==================
Something went wrong with that request. Please try again.