Skip to content

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:

There are three main consequences to this:

  1. Our materials are organised in a certain way (according to the four-way split suggested by Diataxis).
  2. We superimpose three more categories to organise the content across all materials and facilitate self guided studying: Pathways, courses and lessons (see below).
  3. All training materials must be self-contained to ensure that they can be studied without any further guidance by a teacher.

Preparation

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

Tutorial

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.

Lesson

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.

Course

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.

Pathways

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.

Best practices:

  • 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