Get started with GitBook and GitHub a small guide

In this blog post I want to point out the great documentation topic GitBook.

The first time I noticed GitBook, was in a hands-on workshop, when I asked the presenters how they create and update their good looking workshop documentation.

I directly tried out the free GitBook version  for one of my GitHub projects and I noticed the awesome navigation, search, feedback and the responsive webpage capabilities which is all provided out of the box by GitBook. That’s awesome.

Here is a small gif that shows the GitHub readme.md page and the GitBook page at the same time.

gitbook-page-and-github-page

Sure there are many more functionalities in GitBook such as teaming, but to use these functionalities you need a paid license and I didn’t tried that out.

Here is a small “get started guide” I created from my perspective to get started with a GitBook page.

Continue reading

“code pattern” – my point of view

Today I want to focus on a interesting question I got:  “Why does IBM call something a code pattern and not just sample?” The question was related to my last blog.

Here is my personal point of view

First, there is no existing definition of the word pattern in combination with usage of the word code.

  • Based on the given definition, here is my free interpretation of the word pattern :
    “A pattern is something you can reproduce in different areas, and this interpretation is more less always comparable to a sample.  “
  • The main difference between sample and pattern from my point of view is: 
    “A pattern is always created to reproduce something which worked and will work again and this is not the case with a sample.”

Sure, a code pattern is NO design pattern  😉 . The combination of the words design and pattern has an official definition.

From my understanding, IBM uses the word pattern in combination with code, with the intention of showing you that you can reuse the code in the way you want.

A code pattern does NOT need to be related to IBM products or IBM services, but it should be related to one or more technologies and should contain code, which a developer is able to reuse under an apache license.

Structure of the code pattern

A code pattern should always contain:

  • Clear definition of the used technologies
  • Should contain code which can be used to instantiate an application
  • Should contain the possible deployment models (cloud, local, and so on) of the application

A code pattern should always have the following high level structure:

  • Summary (main objective),
  • Description (what it does)
  • Flow (how it works)
  • Instructions (how to instantiate)
  • … and for sure the code, which is available on github

This was my personal perspective on the definition of a code pattern, based on my experience with code patterns so far.

I hope this was helpful for you and feel free to provide feedback 😉

Let’s see what’s next?

Greetings,

Thomas

PS: By the way, you can use the IBM Cloud for free, if you simply create an IBM Lite account. Here you only need an e-mail address.