Making a Tutorial
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.
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
- 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.
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.