From 9f4b24a3d71392c8ec3dd42cbccac9e6000699c4 Mon Sep 17 00:00:00 2001
From: Peter Ebert <pebert@mpi-inf.mpg.de>
Date: Fri, 30 Dec 2016 15:41:57 +0100
Subject: [PATCH] DOC: improved documentation of process template

---
 template/README.md                 | 28 +++++++++++++++++++++-------
 template/deep_process_template.xml | 27 ++++++++++++++++++++++++++-
 2 files changed, 47 insertions(+), 8 deletions(-)

diff --git a/template/README.md b/template/README.md
index 254fa6c..5510777 100644
--- a/template/README.md
+++ b/template/README.md
@@ -1,30 +1,44 @@
 # Templates for new documents
 
-## New Process document
-In order to document a new analysis, please download the file `deep_process_template.xml` and fill out all sections with you favorite text editor.
-Certain entries must appear only once, whereas others, e.g., those to specify reference and output files,
-can occur as often as needed in the *Process* file - just copy the XML skeleton for a new entry.
+## Create a new Process document
+In order to document a new analysis, please download the file `deep_process_template.xml`
+and fill out all sections with your favorite text or XML editor.
+Certain entries must appear only once (*Process* name, version and author as well as the description),
+whereas the remaining sections can contain as many entries as needed;
+you can list any number of input, output and reference files and as many tools as needed in the
+Software section to give a complete step-by-step documentation of the analysis pipeline.
 
 An important note: please verify that the template you are using lists the following style sheet document at the top:
+
 ```xml
 <?xml version="1.0"?>
 <?xml-stylesheet type="text/css" href="http://deep.mpi-inf.mpg.de/DAC/files/style/deep_process_style.css"?>
 ```
 This is required to render the *Process* XML file into a nicely readable form when opened with a standard web browser.
 Also, please make sure that there is no encoding specified, i.e., ***the following is considered bad practice***:
+
 ```xml
 <?xml version="1.0" encoding="ISO-8859-1"?>
 <?xml-stylesheet type="text/css" href="http://deep.mpi-inf.mpg.de/DAC/files/style/deep_process_style.css"?>
 ```
 
+For a more detailed description, please refer to the following publication:
+
+["A general concept for consistent documentation of computational analyses", *Database* 2015](https://dx.doi.org/10.1093/database/bav050)
 
-#### Technical note: encoding
+##### Technical note: encoding
 If you are wondering why there should no encoding be specified in the *Process* document itself: the encoding for all DEEP *Process* files is set in the *XML schema* file.
 This ensures that all *Process* files are read with the same encoding when using the [validation script](../validation/) and the respective schema file.
 
 
-#### Technical note: style sheet
+##### Technical note: style sheet
 If you are wondering why the link the *Process* template does not refer to this repository: repositories are not meant for file hosting like a regular
 web server. To discourage users from nevertheless doing so, the Github software forces the [MIME type](https://en.wikipedia.org/wiki/Media_type)
 of the style sheet document to be `text/plain` instead of `text/css` when it is loaded in your browser. Unfortunately, the browser cannot recognize
-(interpret) the style sheet as such in this scenario and, hence, the *Process* document would not be rendered as intended. 
\ No newline at end of file
+(interpret) the style sheet as such in this scenario and, hence, the *Process* document would not be rendered as intended.
+
+
+## Validate the new Process document
+After having created a new *Process* document, the most convenient way to check it for syntactical errors
+(e.g., missing software versions or invalid characters) is to use the small Python script provided in this
+repository [validation script](../validation/).
diff --git a/template/deep_process_template.xml b/template/deep_process_template.xml
index 354a0be..4c052a6 100644
--- a/template/deep_process_template.xml
+++ b/template/deep_process_template.xml
@@ -1,15 +1,25 @@
 <?xml version="1.0"?>
 <?xml-stylesheet type="text/css" href="http://deep.mpi-inf.mpg.de/DAC/files/style/deep_process_style.css"?>
+<!-- Header above: leave that unchanged -->
+
+<!-- Process documentation: change as necessary -->
 <process>
+	<!-- Process name: by convention, should be 3 capital letters -->
     <name>PROC</name>
+	<!-- Process version: by convention, (single-digit) number, increment by one after update -->
 	<version>0</version>
+	<!-- Process author: state full name and valid institutional e-mail address -->
 	<author>
 		<name>Author_Name</name>
 		<email>Author_Email</email>
 	</author>
+	<!-- Process description: free-text field, describe what, how and why this analysis does.
+	 If you have to use special characters like ">" or "&", remember to escape them properly. -->
     <description>
         Description
 	</description>
+
+	<!-- Process input files: you can copy the "filetype" block as often as necessary -->
 	<inputs>
 		<filetype>
 			<identifier>Input_ID1</identifier>
@@ -18,6 +28,8 @@
 			<comment>Comment_1</comment>
 		</filetype>
 	</inputs>
+
+	<!-- Process reference files: you can copy the "filetype" block as often as necessary -->
 	<references>
 		<filetype>
 			<identifier>Reference_ID1</identifier>
@@ -26,6 +38,10 @@
 			<comment>Comment_2</comment>
 		</filetype>
 	</references>
+
+	<!-- Process output files: you can copy the "filetype" block as often as necessary; you only need to document
+	 output files that are stored, i.e., that are available in downstream analysis. Do not list intermediate or
+	 temporary files that are anyway discarded after a successful pipeline run -->
 	<outputs>
 		<filetype>
 			<identifier>Output_ID1</identifier>
@@ -34,13 +50,22 @@
 			<comment>Comment_3</comment>
 		</filetype>
 	</outputs>
+
+	<!-- Process step-by-step instructions: you can copy the "tool" block as often as necessary.
+	 Note that special characters as part of the command line must not be escaped. Enclosing the
+	 command line in a <![CDATA[  ]]> block avoids interpretation of its content as XML stream. -->
 	<software>
 		<tool>
 			<name>Tool_Name</name>
 			<version>Tool_Version</version>
-			<command_line><![CDATA[ TOOL_CMDLINE ]]></command_line>
+			<command_line>
+				<![CDATA[
+					TOOL_CMDLINE
+				]]>
+			</command_line>
             <loop>no_looping</loop>
 			<comment>Comment_4</comment>
 		</tool>
 	</software>
+
 </process>