Create technical documentation

[OliverWoolland]

Technical documentation for the SDR should be produced, this should stem from the project's README file and link to more detailed help and guides. In our 2022-11-26 project meeting we agreed to adopt the diataxis style for documentation.

This is our current documentation to do list:

Tutorials

• Write Tutorial: Simple journey, uploading reference file to reference SDR instance and running reference workflow #113

How tos

• Write How-To: Deploy a new instance of the SDR #114
• Write How-To: Produce the SDR's input files #117
• Write How-To: Add new tools (mostly referencing existing Galaxy documentation) with examples of our tools as templates #118
• Write How-To: Configuring the job submission engine (how we've done it - config files etc - and links to advanced info) #116
• Write How-To: Use Mothra #115
• Write How-To: How to call Galaxy workflow using API #123

Explanation pieces

• Write Explanation: General overview of the SDR for repo readme #124
• Write Explanation: Update and beautify Galaxy landing page #125
• Write Explanation: SDR workflows (outside of Galaxy) #126
• Write Explanation: SDR tools and workflows (inside of Galaxy, including tags) #127
• Write Explanation: Description of the Teklia produced SDR tools #119
• Write Explanation: Ansible scripts and SDR-ification #120
• Write Explanation: Detail SDR deployment approach to SSL certificates #129

References

• Write Reference: Implementation details of individual custom SDR tools #121
• Write Reference: Populating variables of Ansible deployment #122
• Write Reference: Collection of tools in WorkflowHub #128

Please let me know if you have suggestions for more documents and I will add them to this list. Additionally please give me your thoughts about the use of the diataxis framework.

[llivermore]

For reference, see:

• https://www.brachiograph.art/
• https://diataxis.fr/adoption/