Dave's first edit pass

.gitignore

@@ -1 +1,2 @@
 output
+docs/_build

.project

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>shariant_docs</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+	</buildSpec>
+	<natures>
+	</natures>
+</projectDescription>

docs/integration/basics/getting_started.md

@@ -1,7 +1,5 @@
 # Integration Getting Started
 
-Steps
-
 ## Step 1 : Defining the sync tool
 
 Shariant accepts the upload of classifications via REST and is authenticated via OAUTH2.
@@ -10,23 +8,32 @@ Shariant will not initiate any communication to your system (e.g. you wont have
 You will need to have a tool running with access to your curation data on your network/cloud. This will be responsible for providing classifications to Shariant and if possible, automatically providing Shariant classifications as annotations to your system.
 
 If your curation system is one that we've seen before, we can get you started with integration code.
-If it's new, we do have a python library that will provide some structure around the calls.
+If it's new, we do have a Python library that will provide some structure around the calls.
 If your IT team already has a series of integrations, they're welcome to use any existing framework to perform the syncing.
 
 ## Step 2 : Accessing and identifying data for the sync tool
 
 Your curation system may have an API to access its data, it might have a database on your network that you can query or you might have to do a regular extract to a file and process that.
-In addition it is unlikely you'll want to upload all records from your system immediately. Some systems may let you add arbitrary tags to your system or you may already have a column to indicate that the classification is in a complete state.
+
+You probably don't want to upload all of your variants immediately, so it is useful to add some tags/fields to your system to help decide what to share and help with the integration.
+
+* Last modified date
+* Whether the variant is complete
+* Share level
+
+Last modified can be used to determine what you need to send to us since your last upload. The other fields are to determine whether to send the classification to us, and what the initial share status should be.
 
 Some additional questions you may want to ask at this point:
-How frequently will the sync process take place?
-Will you re-upload all relevant records or only the ones that have changed?
+
+* How do I uniquely identify a record from my lab (probably your internal database primary key)
+* How frequently will the sync process take place?
+* Will you re-upload all relevant records or only the ones that have changed?
 
 
 ## Step 3 : Mapping from your structure to Shariants
 
-Given any individual field you can enter in your system, how does it map to our pre-registered set of evidence keys?
-The tool might just be able to rename the field, it might be more complicated and need to parse through the value to extract segments, or the field might indicate a value for one of our drop downs.
+Given any individual field you can enter in your system, how does it map to our [pre-registered set of evidence keys](https://shariant.org.au/variantclassification/evidence_keys)?
+The sync tool may just need to use a different field name, or the mapping process may be more complicated.
 
 For example, if your system has a Yes/No field called "This gene is known to be associated with X-linked recessive disease." that would map to our field "mode_of_inheritance" with a value of "x_linked_recessive".
 
@@ -41,20 +48,21 @@ Shariant enforces a small base level of required fields
 
 ### Avoid personal identifiable information
 
-You will also need to ensure you don't send us any information that could be used to identify the patient, specifically avoid names and addresses.
-You will also need to ensure users don't enter such information into summaries or other fields you are mapping from your curation system.
+Do not send us any information that could be used to identify the patient, specifically avoid names, detailed pedigrees, birth dates and addresses.
+You must also not enter such information into summaries or other fields you are mapping from your curation system.
+
+Your **lab record id** should be a number like "10125" which doesn't mean anything and can only be matched to a sample or patient if you have access to your own secured patient record system or a record of the mappings.
 
 ## Step 4 : Maintenance & user interaction
 
-It's possible that a small number of your records fail our variant mapping process, or miss out on mandatory information.
-In addition, there will be valid records that run into discordance with classifications from other labs.
+The Shariant API will return error messages for records that fail variant matching or are missing mandatory fields. Someone needs to periodically examine these logs and resolve any issues.
 
 Individual classifications can be assigned to different users, if there's something on a classification that requires attention, the linked user will be notified by email.
 Some issues can be fixed by updating your curation system and waiting for the next sync, others will require interaction with the Shariant website.
 
-Work out which users will be repsonsible for which records, though any member of your lab has access to fix any issue with any of your lab's classifications.
+Assigning resposible users may cause less coordination work for your team, though any lab member can see and edit all of your lab's classifications.
 
 ## Step 5 : How best can your system integrate data from Shariant
 
 Shariant provides an API for bulk downloading of classifications.
-Currently we only provide classifications in our own JSON format, but on the roadmap is support for more export options such as VCF. It is expected that some systems will need custom solutions here, so some work may get done as the requirements come in.
+Currently we only provide classifications in our own JSON format, but on the roadmap is support for more export options such as VCF. It is expected that some systems will need custom solutions here, so some work may get done as the requirements come in.

docs/integration/basics/overview.md

@@ -1,18 +1,18 @@
 # Integration Overview
 
-You have variant classifications in your own curation system and you want them to be in ours.
+### Your variant classifications into Shariant
 
-What are the basic goals here:
+Goals:
 
 * Ensure we can consistantly match records to variants.
 * Compare classifications (across different labs) for the same variant in a meaningful way.
 * Format the classification for submission to other databases such as Clinvar, which will have their own structure requirements.
-* (Avoid providing patient identifiable information).
+* Avoid providing patient identifiable information.
 
-Also we have variant classifications in our database and you want access to them in your curation system.
+### Our variant classifications into your curation system
 
-What are the basic goals here:
+Goals:
 
 * Ability to retrieve an extract from our Shariant and import it in a different track into yours
 and/or
-* Be able to quickly use the web interface to search for relevant variants
+* Be able to quickly use the web interface to search for relevant variants

docs/integration/basics/sharing.md

@@ -4,20 +4,22 @@ Shariant has the following concepts for handling who has access to what
 
 |Body|Meaning|
 |----|-------|
-|Organisation|Sometimes labelled Institution, e.g. SA Pathology, VCGS|
-|Lab|A lab belongs to an organisation, e.g. SA Pathology’s Familial Cancer, Frome Road|
-|User|A user has their own Shariant login. Users should match real people one to one, with the exception of a user account specifically setup to sync records between a lab’s system and Shariant.|
-|Variant Classification|A variant classification will be owned by a user and a lab|
+|Organisation|Aka Institution (eg SA Pathology, VCGS) |
+|Lab|Lab in an organisation (eg SA Pathology’s Familial Cancer, Frome Road) |
+|User|Each lab member should have their own login. The sync tool will have a separate account. |
+|Variant Classification|A variant classification will be owned by a user and a lab |
 
-A user can belong to multiple labs, though typically a user will only belong to one.
+A user can belong to multiple labs, though typically a user will only belong to one. Please contact us when a staff member leaves your lab and we can disable access to your lab's records.
 
 Variant Classifications can be seen in two modes.
 
-* The live editable copy.
-* A read-only version shared at a given point in time.
+* The live editable copy (there is only 1 of these)
+* A read-only version shared at a given point in time
+
+There can be multiple read-only versions for each live editable classification.
 
 If you or someone from your lab created a variant classification, you will be dealing with editable copy.
-If someone from outside your lab shares a record with you, you will be dealing with the specific version that they deemed to share. If they make changes and share it again, you will then have access to the new version. This is inversely true of records you share.
+If someone from outside your lab shares a record with you, you will be dealing with the specific version that they deemed to share. If they make changes and share it again, you will then have access to the new version. The same applies when you share records with them
 
 Users with access to the editable version can elect to share the record in its current state as long as there are no outstanding validation errors. This will give other users read only access to the data as it is when the publish action was performed.
 
@@ -32,4 +34,4 @@ Sharing can be done at several levels. Each level encompasses the level before i
 
 See the Sharing section in the API for information on how to utilise these share levels.
 
-The purpose of Shariant is to share records. The lower share levels are intended for records that are awaiting review or more information - not as a permanent half sharing state.
+The purpose of Shariant is to share records. The lower share levels are intended for records that are awaiting review or more information - not as a permanent half sharing state, and the system will automatically share records to other labs within Shariant after 6 months to ensure progress down the Sharing lifecycle.

docs/integration/basics/variant_matching_overview.md

@@ -1,8 +1,5 @@
 # Variant Matching Overview
 
-## Scope
-Shariant Variant Normalisation Process describes the variant normalisation protocol implemented for the Australian Genomics initiative, Shariant. It should be read in conjunction with Shariant Technical Overview.
-
 ## Abbreviations
 
 |abr|Meaning|