Documentation Structure

The documentation for this site is organised using the Diátaxis documentation framework, to give four types of documentation as summarised in the figure below. Structuring the documentation in this way is intended to help you find the most appropriate resources: both for the completing the site tasks and working your way through the topics we will cover. The different sections are also colour-coded to help orient you where you are, and organise your own notes.

The heart of the site are the All Tutorials: which will be the main focus for the labs in this site

• All Tutorials have a series of learning outcomes, which will relate to the overall learning outcomes of the site. At the end of each Workshop you should have achieved a something that relates concretely to the overall topic and goal of the site. However the Tutorials is also a pathway: you will begin with relatively little experience of the topic, idea, or skill. And should end with something to show that helps you to build your own understanding.

  However a Tutorial will not cover everything you need to complete the site. Also, you will need other kinds of resources to help you complete the Tutorials. Those other resources are

• How-To guides can be found in most Tutorials: they help you to achieve a specific goal, usually in a step-by-step manner. How-To guides also do not give Notes explaining ‘why’ things are done in a certain way, or provide a Reference to related material — although they may link to these. Instead the aim of a How-To guide is to answer questions as “how do I do x?” or “what code should I use to achieve y?

  Often a Tutorial will introduce a specific How-To: but it is up to you how much of it you use later. You may, for instance, choose to make you own notes of how to achieve a specific goal — indeed these is strongly encouraged. Or you may find some How-To’s setting up environment something you refer back to frequently.

• Notes provide the background ‘why’ for a specific How-To or Tutorial. Notes should provide a deeper understanding of a topic: but they won’t tell you ‘how’ to do something. Most Tutorials will have Notes giving the context, background, theory, or history of the topic being introduced in that activity. Notes will also link back to, or summarise, the content from lectures or other material to help you gain a full understanding of the site content.

• Finally, Reference material provides the basic facts you will need in other activities. Examples of Reference material are links to the API or source code for a specific library, data-sheets for components or other devices, and papers and books from the academic literature expanding on a specific topic or area. This allows you explore the summary outlined in a Note{: .violet}: or to understand the specific technique introduced in a How-To in more detail.

You will need different kinds of documentation at different times: and you may use some types of documentation more frequently. For instance we expect you will only go through each Tutorial once — but you may refer to the How-To guides within the Tutorials more frequently. So we have also collected the various types of documentation together, to make it easier to go back to a specific piece of material more easily. If you can’t find something, though, ask your site tutor for help.