README.md

# Templates for new documents

## 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
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
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.


## 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/).