Gitbook — Dokümantasyon İçin Nihai Çözüm

Merhaba,

Çalışırken hem öğrendiklerimi hem de karşılaştığım sorunları nasıl aştığımı, dokümante etmeyi çok seviyorum. Hatta bazen öğrenmeyi planladığım bir konu için çalışmaya dokümante ederek başlıyorum.

Uygulamaların kurulum ve kullanımları, pratik örneklerin uygulanması, yeni kavramlar, teknolojiler ve bunların tanımları gibi daha pekçok şey. Böyle bir alışkanlık daha iyi ve düzenli öğrenebilmeyi de sağlıyor.

Bu ihtiyaç için yıllardır çok farklı uygulamaları denedim. Microsoft araçları, OneNote , hatta içlerinde Windows Help dosyası oluşturmak için kullanılan bir araç bile vardı. :)

WinCHM — Windows Help File Maker

Bu uygulamanın en güzel yanı tek bir dosya içerisinde tüm kütüphaneyi taşıyıp paylaşabiliyor olmanız. Bir de sayfaları, web sayfası olarak kitaplığa ekleyebildiğiniz için istediğiniz gibi tasarım yapmak, hatta javascript içerikler bile ekleyebilmek mümkün.

Tabi şu dönemde dokümantasyon oluşturmak için bu kriterler ile sınırlı kalamayız. Daha farklı, önemli ihtiyaçlarımız var.

• Bulut tabanlı çalışabilmek,
• İçeriğe farklı makine ve lokasyonlardan erişebilmek ,
• Bir kullanıcı grubu ile içerik oluşturmak ve kullanabilmek,
• Dinamik olarak yedeklemeler yapabilmek,

aklıma gelen ilk beklentiler.

Gitbook ile dokümantasyona başlayalım artık :)

Kılavuzu şöyle hazırladım ;

1. Hesap Oluşturulması ( Registration )
2. Kütüphane ve İçerik Oluşturulması
3. Github ile senkronizasyon
4. Başka takım üyelerini de dahil etmek

1. Hesap Oluşturulması

https://app.gitbook.com/ adresine gidiyoruz önce

Register işlemini bir Google hesabı ile veya Github hesabı ile yapabilirsiniz. Benim tavsiyem Github hesabı ile yapmanız. Çünkü zaten verileri senkron etmek için bir Github hesabı tanımlamanız gerekecek.

1. a ) Github hesabı oluşturmak ( hesabınız varsa bu adımı geçin )

Github mı ? Come ooonn diyenleri duyar gibiyim. :) Yine de anlatayım.

github.com/login adresine gidip animasyondaki adımları takip edin.

2. Kütüphane ve İçerik Oluşturulması

Artık bir Github hesabımız olduğuna göre, Gitbook’a bu hesapla giriş yapıp ilk içeriğimizi oluşturalım.

Documentation kısmından ; Space, Collection veya Import ile ilerleyebilirsiniz.

Benim yaklaşımım önce Collection, altında ise Space oluşturmak yönünde. Jmeter tarafında öğrendiklerimizi dokümante edeceğiz diyelim ;

Apache Jmeter == Collection

API / Servis Testleri == Space. ( Jmeter’da Servis Testleri Nasıl Yapılır ? )

Database Testleri == Space

Jmeter & Selenium == Space ( Jmeter ile Selenium’un Birlikte Kullanımı )

şeklinde bir mimari daha iyi olacaktır.

Örnek bir konu dokümantasyonu

Space’i de oluşturduktan sonra artık altında dilediğiniz kadar page veya subpage oluşturabilirsiniz. Bu noktada geleneksel ağaç yapısı şeklinde içeriklerinizi yaratabilirsiniz.

Not : Sağ üst kısımda Merge ve Edit butonlarını göreceksiniz. Bu içeriği ya kaydettiğinizi yada henüz üzerinde çalışıyor olduğunuzu gösteriyor.

Merge sonrası ayrıca Senkron ve Paylaşma aksiyonları da alabilirsiniz.

3. Github ile senkronizasyon

Her ne kadar bulutta kayıt yapıyor olsak da çalışmaları bir de Github hesabımıza senkron edersek içimiz daha rahat olur.

İçeriklerinizin üst kısmındaki Integrations kısmını takip edin

Github senkronizasyon ayarlarına sol menüde Integrations altından da ulaşabilirsiniz.

Gitbook sizi, Github tarafına, bilgileri girdikçe otomatik bağlıyor.

Github : Account, Repo, Branch bilgileri tanımlanmalı

Burada dikkat edeceğiniz önemli 1–2 konu var.

1. Github tarafında repo ayarlarını public ( açık ) ya da private ( özel ) ne seçtiğinize dikkat edin. Dokümantasyon özel ise private seçip ilerlemenizi tavsiye ederim.
2. İlk senkronizasyonun nereden nereye yapılacağı. Bu seçenek de yine Integrations altında var. Gitbook’ta bir dünya içerik oluşturup, sonra içerisi bomboş bir Github hesabına senkron edecekseniz seçiminizi aşağıdaki gibi yapın.

4. Başka takım üyelerini de dahil etmek

Hayat paylaşınca güzel.

Bir elin nesi var iki elin sesi var.

Küçük çaplı bir takımınız, ekibiniz, çalışma grubunuz varsa onları da içerik paylaşımınıza ve üretimine dahil edebilirsiniz.

Settings > Invite teammates deyip ;

Kullanıcı davetlerini oluşturabilir, katılacak kişilerin rol ve yetkilerini belirleyebilirsiniz.

Sonuç :

Aslında uygulamanın daha birçok özelliği var. Kullanınca keşfedersiniz siz de. Ancak en temel işlevler bunlardı. Çok uzatmak istemedim. :)

Kurumsal yapılar altında özellikle Confluence gibi veya Open Source alternatif olması açısından WikiJS ve XWiki gibi çok daha fazla gelişmiş araçlar var. Pek çoğumuz bu araçları kullanıyoruz. Ancak onlar bize ait değil. İçerisindeki veriler de.

Bireysel, kolay kullanılabilen, her türlü popüler platform ile senkron olabilen, kurulum gerektirmeyen ayrıca lisans maliyeti olmayan bir uygulama olması Gitbook’u tercih etmemi sağladı.