📝 Document samples and specimens

🔥 Remove test text

docs/source/design/concepts/samples_and_specimens.rst

@@ -1,12 +1,13 @@
-=====================
+.. _samples_and_specimens:
+
+========================
 Samples and Biospecimens
-=====================
+========================
 
 Although similarly named, samples and biospecimens refer to different things:
 
-- A **sample** is a physical piece of tissue, blood, or other material taken
-from a patient.
-- A **biospecimen** is a part of that sample, e.g. an aliquot of a sample. 
+    * A **sample** is a physical piece of tissue, blood, or other material taken from a patient.
+    * A **biospecimen** is a part of that sample, e.g. an aliquot of a sample. 
 
 While samples and biospecimens are distinct concepts, they share much in common.
 In fact, when the ingest library was first written, its primary target API, 
@@ -20,11 +21,20 @@ biospecimens.
 
 A sample has qualities:
 
-* A sample may have ino
+    * A sample may have information about itself, such as the type of tissue it is, the type of tumor it comes from, when the sample was collected from the participant, its volume, etc.
+    * A sample may have information about shipping, such as the date it was shipped
+
+
+As discussed above, a biospecimen is a child class of sample, so biospecimens
+may have all of the same qualities of a sample*. In addition:
 
-A biospecimen takes on 
-This
-is the smallest unit that a piece of biological material can take, as
-represented in the ingest library.
+    * a biospecimen may have information about its concentration
+    * a biospecimen may have information about its analyte type (e.g. DNA vs RNA)
+    * a biospecimen may have information about the consent under which it was collected.
 
-Some 
+Biospecimen is designed as a child class of sample to provide for
+backwards-compatibility with older ingest packages that existed before the
+sample concept. Moving forward, it is advised to use the sample class when
+extracting information that is most related to the sample and use biospecimen
+only when extracting information that is specific to the biospecimen
+(such as concentration, analyte, and consent information).