Tutorial how to make tutorials using Google Code Labs. Gangnam style.

It is hard to create a good tutorial which explains and express our thoughts and teach others our solution. I really like tutorials from google — they are easy to read and they present solution step by step. They show how much time is left until the end of the tutorial (top right corner). The good news is that Google Labs is now open for everyone. You can create own tutorial based on this tool. I have created a tutorial based on a guide from developer.tomtom.com with title “Creating a custom vector map style” https://developer.tomtom.com/maps-sdk-web/tutorials-advanced/creating-custom-vector-map-style

Google code labs

Before we start please have a look on sample tutorial written in this tool. https://codelabs.developers.google.com/codelabs/android-lifecycles/index.html?index=..%2F..%2Findex#0

There are two ways of creating a tutorial with Google Code Labs tool. (GCL in the next part of the articles, I will use this shortcut). First one is to use “Google Docs” with special formatted text which can be converted to tutorial. Such approach has advantage:

but has also disadvantage:

  • you will need to copy to your Google Docs document with a part of text from google docs template.
Template is available here, but you need to join the Google Group (https://groups.google.com/forum/#!forum/codelab-authors ) to get access to: https://docs.google.com/document/d/18dnMdUJQaGKY1Tit_-fO1YOpOpAbA4hh0YDXQlCEjvA/edit#heading=h.woxdyaltjwz2 )

Better way is to use markup language md, and we will go in that way.

GCL can be created by Google docs or by markup language, can be stored locally or hosted on any server like github.io.

https://github.com/googlecodelabs/tools this is a very important link with possibilities provided by GCL and there is a tool for parsing markup language. Here is a download page of the tool: https://github.com/googlecodelabs/tools/releases.

Of course if you want you can build the tool from sources. Download a bin file (for me it is claat-linux-amd64 ) and save on disk and give executive permissions chmod +x claat-linux-amd64. It is worth to add this directory to PATH to have this tool available from any place. In my case in ~/.bashrc I have added that line:

export PATH=$PATH:/home/username/bin/

If all works when we run claat-linux-amd64 help we should get help message.

Gangnam style.

Gangnam is a reach district of Seul ( https://en.wikipedia.org/wiki/Gangnam_District ) and a name of the song.

play music and continue …

Create a file: gangnam.md and open this file in favorite editor. Some basic information about markup language for GCL are here https://github.com/googlecodelabs/tools/tree/master/claat/parser/md but it is a basic guide.

Firstly we have to inform users what the document is about:

author: Mariusz Saramak
summary: TomTom Creating a custom Gangnam vector map style
id: 24242443
categories: sdk
environments: js
status: draft
feedback link: github.com/tomtom-gangdam-style-for-map
analytics account: 0

To specify the title of tutorial just use one “#” like below:

# TomTom Creating a custom Gangnam vector map style

To specify the title of the first step, use two chars “##” right after title provide information about how much time user should spend on that part.

## Overview of the tutorial
Duration: 0:05

Text and lists

Now we can add text, markup md language is simple. More information about md language you can find here https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

First text with lists:

This tutorial shows you how to create custom vector map style. In this tutorial you will do the following:
* Modify a default TomTom style for vector maps with use of the Maputnik editor 
* Apply the newly created style
Prerequesites
* API key
* Npm and Node.js
We recommend you to have npm and Node.js already installed on your machine to quickly boot up a http server.

until this moment we have that

Next we add some positive information:

Positive
: It is possible to have a single key(app) for all TomTom services, but you can also choose : to have individual keys for the different services.

We can add negative information too:

Negative
: To get an API key you need register or sign in to TomTom Developer Portal. Request an evaluation API key to access the service you want to use the SDK with.

Lets check what we have:

//to convert md file to html file
claat-linux-amd64 export gangnam.md
//to download dependencies of html file and run a simple server on http://localhost:9090/
claat-linux-amd64 serve gangnam.md

Second slide and download link

## Download our Maps SDK offline examples
Duration: 0:10
Before you start, you need to download the latest version of our offline functional examples from [here](https://developer.tomtom.com/maps-sdk/maps-sdk-downloads).

But when we change “here” description to “Download functional examples” link for download will change to big green button.

Adding image

![image_caption](https://s3-eu-west-1.amazonaws.com/released-artifacts-3.x/assets/tutorial_images/creating-styles/step1.png)

Adding code

``` bash
npm install && npm start
```

Here we have example of adding bash snippet of code, but it can be any language. In example: java, kotlin, xml, js

We continue with tutorial and we should create document like that:

https://raw.githubusercontent.com/tomtom-gangdam-style-for-map/tomtom-gangdam-style-for-map.github.io/master/gangdam.md

What DOESN’T work

  • Force a new line. Md says about “\” two spaces, two enters, &nbsp; chars or <br/> I tried all and I can not force GCL to create new line :(
  • list with more then one level — I tried with no success.
* list first level
 * list second level
  • list with URLs — When I tried to add URL to the link list, it didn’t generate a list
  • Download button — just doesn’t work

Publishing a result

claat-linux-amd64 export gangnam.md
claat-linux-amd64 serve gangnam.md

Generated html file push to your github.io webpage, in my case:

git add -A
git commit -a -m “Generated version”
git push

and generated index.html file should be in my repository

Now we can check result on page:

And there it is — looks fine.