Merge pull request #184 from Seshat-Global-History-Databank/roles-doc…

…s-restructure Roles docs restructure
Seshat-Global-History-Databank · Nov 28, 2024 · b29b64a · b29b64a
2 parents c3088b6 + 02ea05f
commit b29b64a
Show file tree

Hide file tree

Showing 11 changed files with 34 additions and 90 deletions.
diff --git a/docs/source/researcher/cliopatria.rst → docs/source/cliopatria.rst b/docs/source/researcher/cliopatria.rst → docs/source/cliopatria.rst
@@ -11,7 +11,7 @@ Working with the Cliopatria borders dataset
 
 Cliopatria is available as a stand-alone dataset which is stored and documented at `github.com/Seshat-Global-History-Databank/cliopatria <https://github.com/Seshat-Global-History-Databank/cliopatria>`_.
 The data takes the form of a single GeoJSON file, a format that can be loaded by a wide variety of software for handling geospatial data.
-Whilst Cliopatria can be accessed via the `Seshat API <api.rst>`_, in most cases it is faster and more convenient to download the dataset directly from the GitHub repository and work with it locally.
+Whilst Cliopatria can be accessed via the `Seshat API <python_api.rst>`_, in most cases it is faster and more convenient to download the dataset directly from the GitHub repository and work with it locally.
 
 A great way to get started exploring the Cliopatria dataset is to open it in the Jupyter notebook examples found inside the `github.com/Seshat-Global-History-Databank/cliopatria <https://github.com/Seshat-Global-History-Databank/cliopatria>`_ GitHub repo.
 The `notebooks` folder contains a processing script to add colors to the dataset, alongside a notebook which loads the data in GeoPandas and includes an interactive Folium plot.
@@ -20,7 +20,7 @@ Follow the README instructions in the `notebooks` folder.
 
 .. tip::
 
-    You may want to start by reading the `Software tools <software-tools>`_ page to ensure you have Python and Git installed on your computer.
+    You may want to start by reading the `Software tools <software-tools.rst>`_ page to ensure you have Python and Git installed on your computer.
 
 
 Requesting edits to the Cliopatria dataset
@@ -38,15 +38,15 @@ To request a specific edit to the Cliopatria dataset, such as changing the shape
 
 1. Click the "Edit" button on the polity page of interest.
 
-    .. image:: ../img/edit_cliopatria.png
+    .. image:: img/edit_cliopatria.png
         :alt: Edit Cliopatria
 
 2. Fill out the edit page that opens and use the Private Comment box to explain in detail the change you would like. Note the ID of the shape you would like to change. If the change you are requesting is to multiple shapes, please list all the IDs. Click the "Submit for Review" button.
 
-    .. image:: ../img/edit_cliopatria_part_2.png
+    .. image:: img/edit_cliopatria_part_2.png
         :alt: Edit Cliopatria form
 
-3. This should open a private comment thread where you can discuss the edit with other researchers. See the `Discussing data edits via private comments <getting_started.rst#discussing-data-edits-via-private-comments>`_ section for more information. Assign the comment to the person who is best placed to review the edit, e.g. someone who works on Cliopatria (see the `team <../team.rst>`_ page for more information).
+3. This should open a private comment thread where you can discuss the edit with other researchers. See the `Discussing data edits via private comments <getting_started.rst#discussing-data-edits-via-private-comments>`_ section for more information. Assign the comment to the person who is best placed to review the edit, e.g. someone who works on Cliopatria (see the `team <team.rst>`_ page for more information).
 
 4. The reviewer will check the edit request and either make it or ask for more information via the comment thread.
 

diff --git a/docs/source/researcher/datasets.rst → docs/source/datasets.rst b/docs/source/researcher/datasets.rst → docs/source/datasets.rst
diff --git a/docs/source/expert/index.rst b/docs/source/expert/index.rst
diff --git a/docs/source/researcher/getting_started.rst → docs/source/getting_started.rst b/docs/source/researcher/getting_started.rst → docs/source/getting_started.rst
@@ -1,7 +1,7 @@
 Getting started with Seshat data
 =================================
 
-This section of the documentation provides information on how to get started with accessing Seshat data as a researcher, both through the Seshat website and the Seshat API, as well as the Cliopatria borders GeoJSON dataset.
+This section of the documentation provides information on how to get started with accessing Seshat data as a researcher, both through the Seshat website and the Seshat API.
 
 Creating a login on the Seshat website
 ---------------------------------------
@@ -11,7 +11,7 @@ Creating an account on the Seshat website is the first step to accessing the Ses
 Follow the information on the screen to create your account.
 
 Ensure you are given the correct permissions for your account by contacting the Seshat team.
-See the `team <../team.rst>`_ page for more information.
+See the `team <team.rst>`_ page for more information.
 For most researchers on the project, this will involve being given the "Research Assistant" role permissions, which allows you to make and discuss data edits.
 
 .. warning::
@@ -27,12 +27,12 @@ Once you have created an account and been given the correct permissions, you can
 
     - Editing polity info:
 
-        .. image:: ../img/edit_polity.png
+        .. image:: img/edit_polity.png
             :alt: Edit Polity
 
     - Editing a variable:
 
-        .. image:: ../img/edit_var.png
+        .. image:: img/edit_var.png
             :alt: Edit Variable
 
 2. Fill out the edit page that opens and submit for review.
@@ -46,30 +46,30 @@ Discussing data edits via private comments
 
 In addition to editing the data directly, you can start a "private comment" discussion about a potential data edit, which other researchers can see and comment on.
 Users that lack sufficent permissions, and people not logged in, will not be able to see these comments.
-You can assign a specific person to the comment, if you know their particular expertise is needed. See the `team <../team.rst>`_ page for more information.
+You can assign a specific person to the comment, if you know their particular expertise is needed. See the `team <team.rst>`_ page for more information.
 
 To create a new private comment:
 
 1. Navigate to a polity page and click the "Add a Private Comment" button.
 
-    .. image:: ../img/private_comment.png
+    .. image:: img/private_comment.png
         :alt: Private comment button
 
 2. Write your comment and assign someone to look at it, if needed, then click the insert button.
 
-    .. image:: ../img/comments.png
+    .. image:: img/comments.png
         :alt: Private comment submission
 
 If someone has assigned a comment to you:
 
 1. You will see a notification in the top right corner of the website. Click this to view all the comments assigned to you.
 
-    .. image:: ../img/notifications.png
+    .. image:: img/notifications.png
         :alt: Notifications
 
 2. Click on the comment to view it and respond. Once the discussion thread is completed, the comment can be marked as resolved by checking the checkbox next to the comment and then clicking the "Set Done" button.
 
-    .. image:: ../img/set_done.png
+    .. image:: img/set_done.png
         :alt: Set comment as done
 
 

diff --git a/docs/source/how-to-update-these-docs.rst b/docs/source/how-to-update-these-docs.rst
@@ -29,7 +29,7 @@ How to update these docs yourself
 
 In order to update these documentation pages, first you'll need to ensure you are set up with an account on GitHub and have Git, Python and Anaconda installed on your computer.
 
-If you lack any of these, follow the steps on the `Software tools <software-tools>`_ page to get set up.
+If you lack any of these, follow the steps on the `Software tools <software-tools.rst>`_ page to get set up.
 
 Once you have these pre-requisites, you can follow the steps below to update the documentation:
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -8,29 +8,37 @@ The purpose is to provide a comprehensive knowledge sharing resource for all asp
 Project Roles
 -------------
 
-The documentation is divided into sections based on the role of the reader, which match the access level of accounts on the Seshat website. These roles are defined as follows:
+The pages of these docs which are most useful will depend on the role of the reader.
+These roles, which broadly match the access level of accounts on the Seshat website, are defined as follows:
 
 1. Seshat Databank Admin: A member of the Seshat team responsible for the maintenance and development of the Seshat codebase, database and website.
-2. Researcher: Any researcher contributing to, or consuming, the Seshat data as part of an ongoing Seshat affiliated project.
-3. Seshat Expert: A collaborator with the necessary expertise and permission to approve or reject changes to the Seshat data.
-4. External Seshat Expert: An external collaborator who has the necessary expertise to review and make private comments on Seshat records.
-5. Public User: An academic or other interested party who has created an account on the Seshat website to suggest data edits.
+2. Researcher: Any researcher contributing to, or consuming, the Seshat data as part of an ongoing Seshat affiliated project, with the necessary expertise and permission to approve or reject changes on the Seshat website.
+3. Seshat Expert: An external collaborator who has the necessary expertise to review and make private comments on Seshat records.
+4. Public User: An academic or other interested party who has created an account on the Seshat website to suggest data edits.
+
+Most of the documentation is relevant to **Researchers**, but there is also a section specifically for **Seshat Databank Admins**.
+
+**Seshat Experts** should review `Getting Started with Seshat data <getting_started.rst>`_.
+A list of experts is maintained `here <https://seshatdatabank.info/seshat-about-us/contributor-database>`_.
+**Public Users** will not find this documentation particularly useful, beyond `Creating a login on the Seshat website <getting_started.rst>`_.
 
 Project Documentation
 ---------------------
 
 .. toctree::
    :maxdepth: 2
 
-   admin/index
-   researcher/index
-   expert/index
-   public_user/index
+   getting_started
+   python_api
+   cliopatria
+   datasets
+   research_code
    team
    FAQs
    resources
    software-tools
    how-to-update-these-docs
+   admin/index
    api/index
    code-of-conduct
 
diff --git a/docs/source/public_user/index.rst b/docs/source/public_user/index.rst
diff --git a/docs/source/researcher/api.rst → docs/source/python_api.rst b/docs/source/researcher/api.rst → docs/source/python_api.rst
@@ -12,7 +12,7 @@ The README file in the `examples` folder provides instructions on how to install
 
 .. tip::
 
-   You may want to start by reading the `Software tools <software-tools>`_ page to ensure you have Python and Git installed on your computer.
+   You may want to start by reading the `Software tools <software-tools.rst>`_ page to ensure you have Python and Git installed on your computer.
 
 
 .. note::

diff --git a/docs/source/researcher/projects.rst → docs/source/research_code.rst b/docs/source/researcher/projects.rst → docs/source/research_code.rst
diff --git a/docs/source/researcher/index.rst b/docs/source/researcher/index.rst
diff --git a/docs/source/resources.rst b/docs/source/resources.rst
@@ -38,7 +38,7 @@ There is a second GitHub organisation at `github.com/seshatdb <https://github.co
 .. note::
 
     - For more information on the using Seshat website codbase, see the `Seshat Databank Admin <admin/index.rst>`_ pages.
-    - For more information on using the Seshat API python package and the Cliopatria dataset, see the `Researcher <researcher/index.rst>`_ pages.
+    - There are also pages on using the `Seshat API python package <python_api.rst>`_ and the `Cliopatria dataset <cliopatria.rst>`_.
 
 
 Data downloads & code