Getting started for OBOOK editors¶
The OBOOK is trying to centralise all OBO documentation in one place. It is, and will be, a big construction site, for years to come. The goal is to iterate and make things better.
We follow two philosophies:
- Diataxis for organising our documentation
- Flipped classroom for the organisation of training materials
There are three main consequences to this:
- Our materials are organised in a certain way (according to the four-way split suggested by Diataxis).
- We superimpose three more categories to organise the content across all materials and facilitate self guided studying: Pathways, courses and lessons (see below).
- All training materials must be self-contained to ensure that they can be studied without any further guidance by a teacher.
- Browse through this page: https://diataxis.fr/
- Watch the introduction to the Diataxis framework:
Beyond Diataxis: the OBOOK categories:¶
We just introduced a new concept to OBOOK called
pathways. The idea is that we provide a linear guide for all 6 roles mentioned on the getting started page through the materials. This will help us also complete the materials and provide a good path to reviewing them regularly.
A step-by-step guide to complete a well-defined mini-project. Examples: ROBOT template tutorial. DOSDP template tutorial. Protege tutorial on using the reasoner.
A collection of materials (tutorials, explanations and how-to-guides) that together seek to teach a well defined concept. Examples: Contributing to OBO ontologies; An Introduction to templates in OBO; An Introduction to OBO Application development. While the distinction to "tutorial" is often fuzzy, the main distinguishing feature should be that a lesson conveys a general concept independent of some concrete technology stack. While we use concrete examples in lessons, we do always seek to generalise to problem space.
A convenience content type that allows us to assemble materials from obook for a specific taught unit, such as the yearly ICBO tutorials, or the ongoing Monarch Ontology Tutorials and others. Course pages serve as go-to-pages for course participants and link to all the relevant materials in the documentation. Course usually comprise lessons, tutorials and how-to guides.
A pathway is a kind of course, but without the expectation that it is ever taught in a concrete setting. A pathways pertains to a single concrete role (Ontology Curator, Pipeline Developer etc). It is a collection of materials (lessons, tutorials, how-to-guides) that is ordered in a linear fashion for the convenience of the student. For example, we are developing a pathway for ontology pipeline developers that start by teaching common concepts such as how to make term requests etc, and then go into depth on ROBOT pipelines, ODK and Make.
- Items in the explanation section should conceptually start with a Why or a How question.
- For ordered lists, only use 1. 1. 1., ever 1. 2. 3. This makes it easier to remove and shuffle items during edits