Making a Tutorial

Introduction

This tutorial gives a brief instruction on how to create a new tutorial for the Tutorial Book. It will not explain the elements used within a tutorial since that is already explained in detail in the file template.xml that can be used as a starting point.

Before starting with a new tutorial you can have a look at the existing tutorials to see how they are built up. When you start, you can make a copy of the previously mentioned template file or make a copy of a tutorial that has more or less the format and layout that you want to use. Rename the xml that you copied file to the subject of your tutorial. The format of such a tutorial xml file is tutorial_my_subject.xml where the filename is only using small caps. It is recommended to use a logical name for the subject that matches the subject of your tutorial.

Required tooling

It is not very easy to write xml documents so we will be using a tool for writing our tutorial. A nice XML editing tool that is available for Windows, MacOS and Linux is XMLmind which can be downloaded and used for free for personal use or for open source development. Before writing your tutorial open the template.xml file to see which features can be used like creating sections, paragraphs, unsorted lists, etc.

Writing your tutorial

When writing a tutorial make use of references (external and internal), pictures and videos where possible. A picture says more than a thousand words. Keep the 'instructions' in mind as given in the template. For example external references should have the scope external and pictures should have the otherprops clickable. Of course the clickable feature is only available in the HTML version of the Tutorial Book on the JAL site.

Adding your tutorial to the Tutorial Book

Once you completed your tutorial it has to become part of the Tutorial Book. Depending on the topic it can be in the section about PIC internals, external parts or another section. In order to add your tutorial to the Tutorial Book you have to perform the following steps:
  • Open the file tutorials.ditamap
  • Insert a new topicref
  • Fill in the name of your tutorial xml file in section href
  • Save this file

After having done all the work you should upload both your new tutorial xml file and the tutorials.ditamap file to GitHub. If you where using pictures, make sure that you also upload them to the images directory. When a new Tutorial Book is recreated, your part will be in it.

Updating the change log

At the end of the Tutorial Book, the change log can be found which is stored in the file tutorial_changelog.xml. You should add an extra entry in the most recent table and write what you did, e.g. adding a new tutorial or updating an existing tutorial.

Note: While the Tutorial Book is updated, it remains a draft until it is released. When released, the release date is completed and the Tutorial Book gets a new version number.
Note: The version number and the release date are also mentioned in the bookmeta on the first page of the Tutorial Book in the file tutorials.ditamap. Before releasing, this data should be updated too.

Making sure your tutorial is published on the JAL Website

In the dita folder on GitHub you find a file called TOPUBLISH. This is a plain text file and you should add your tutorial to this file in the format that it is described in the file. It indicates which tutorials should be published as HTML to the JAL Website.