Yapay zekadan makale özeti
- Kısa
- Ayrıntılı
- Bu video, Taksim Uğur Arıcı tarafından sunulan bir eğitim içeriğidir. Uğur Arıcı, 15 yıllık web geliştirme deneyimine sahip bir dijital ürün yöneticisidir ve Facebook Developer Circles İstanbul ile Wright the Dogs İstanbul işbirliği kapsamında konuşmaktadır.
- Video, özgür yazılımlarda belgelendirme ve tutorial yazımı konusunu ele almaktadır. İlk bölümde belgelendirmenin temel başlıkları ve yazılım eğitiminde giriş bariyerlerini önleme yöntemleri anlatılırken, sonraki bölümlerde Vue.js ve OpenID Connect entegrasyonu için "voi dc" adlı paketin kurulumu ve kullanımı adım adım gösterilmektedir.
- Eğitimde ayrıca yazılım belgelerinde ilk kullanım kılavuzu yazma, versiyon bağımlılıklarına dikkat etme, sanal makineler kullanımı, tarayıcı üzerinden erişilebilen geliştirme ortamları ve özgür lisans kullanımı gibi konular da ele alınmaktadır. Sunum, yazılım geliştirme sürecinde tekrarın önemini ve özgür yazılımın avantajlarını da vurgulamaktadır.
- Wright the Dogs İstanbul ve Sunum Hakkında
- Konuşmacı, Facebook Developer Circles İstanbul ve Wright the Dogs İstanbul işbirliği kapsamında bir sunum yapacağını belirtiyor.
- Wright the Dogs İstanbul, İstanbul'da örgütlenen bir topluluk olup şimdiye kadar iki fiziki buluşması olmuş ve Trendyol'un API belgelendirmesi gibi konular üzerine etkinlikler düzenlenmiş.
- Konuşmacı, "Özgür Yazılımlarda Belgelendirme ve Tutorial Yazımı" başlıklı bir sunum hazırladığını belirtiyor.
- 01:26Konuşmacının Kişisel Bilgileri
- Konuşmacı, dijital ürün yöneticiliği alanında danışmanlık veren ve ürün planlama, geliştirme ve yazılım konularında hizmet sunan bir şirkette çalışıyor.
- On beş yıla yakın web geliştirme deneyimine sahip ve günümüzde fabrika makinelerinin uzaktan yönlendirilmesi gibi alanlarda da web teknolojilerini kullanıyor.
- Özgür yazılım etkinliklerine eğitim ve eğitmen olarak katılmaya çalışıyor ve Wright the Dogs İstanbul ve Laravel İstanbul metap gruplarında organizatör olarak bulunuyor.
- 02:48Belgelendirme ve RFC'ler
- Belgelendirme, kayıt altına alma, referans oluşturma, uzlaşma, öğretme ve yönlendirme gibi başlıklara bölünebilecek devasa bir konu.
- RFC (Request for Comments), internet teknolojilerinin ve haberleşme standartlarının belirlenmesinde kullanılan bir standarttır.
- İnternet Engineering Task Force aracılığıyla yayınlanan RFC'ler, farklı araçların birbirleriyle iletişim kurabilmesi için uzlaşı standartları oluşturur.
- 06:15Öğretici Belgelerde Denge Tekerleri
- Öğretici belgelerde öğretme ve yönlendirme, kullanım kılavuzunun hoş geldin aşaması gibi düşünülebilir.
- Bisiklet kullanma örneğinde, denge tekeri sonradan eklenen bir unsur olup, bisiklet kullanmayı öğrenmek için temel bir adımdır.
- Öğretici belge yazarken, temel bilgileri vermeden detaylı konulara geçmek, okuyucuyu öğrenmeye engel olabilir.
- 08:50Öğretici Belgelerde Dikkat Edilmesi Gerekenler
- Öğretici belgelerde önce zemin oluşturulmalı, yani okuyucunun gerekli araçları ve bilgileri sahip olduğundan emin olunmalı.
- Giriş bariyerleri önlenmeli, örneğin bisiklet sürme örneğinde dengede durmak bir giriş bariyeridir.
- Öğretici belgelerde, okuyucunun temel bilgileri ve araçları sahip olduğundan emin olunmalı.
- 09:34Ana Pratik İçin Ek Gereksinimler
- Ana pratik için tekrarlarda ek gereksinimler destekle sağlanmalı, örneğin bir araçta belirli bir görselin base64 encode edilmiş halinin çıktısını kullanmanız gerekiyorsa, bu kodu doğrudan yapıştırarak base64 görseli alabilirsiniz.
- Matematikte pi gibi sabitler, formülleri kullanmayı öğretmek için başlangıçta 3 olarak alınır, ileride hassas hesaplama yapılması gerektiğinde daha doğru değerler kullanılır.
- Yazılımda öğretme ve yönlendirmeye baktığımızda, mümkünse bir kum havuzu (playground) sağlanmalı, böylece kullanıcılar istediği gibi deneyebilir ve başına bir şey gelmez.
- 12:27Kum Havuzu ve Geliştirme Ortamları
- Özgür yazılım kamplarında sanal makineler kullanılarak, katılımcılar kendi makinelerinde kurulum yapabilir ve belirli işlemlerden sonra snapshot alınarak en fazla sanal makinedeki versiyonu düşürme ihtimali sağlanır.
- Günümüzde tarayıcı üzerinden erişilebilecek geliştirme ortamları (JavaScript Fiddle, CodePen gibi) mevcuttur, bu sayede kullanıcılar HTML, CSS ve JavaScript kodlarını tarayıcıda çalıştırabilirler.
- Geliştirilen araçların tutorial'ları İngilizce yazılmalıdır, çünkü Facebook Türkçe'ye özel bir tutorial alanı açmaya gerek görmemiştir.
- 14:51Kod Paylaşımı ve Bağımlılıklar
- Tarayıcıda çalıştırılamayacak ve uygulamanın içinde çalıştırılması gereken kodlar için özgür bir lisans dahil edilmelidir.
- Kodlar herhangi bir Git deposuna (Bitbucket, GitLab, GitHub) yüklenmelidir.
- Bağımlılıkların nasıl kurulup çalıştırılacağını gerekirse dış bağlantıyla vermek gerekir, örneğin Node.js ve npm versiyonları gibi gereklilikler tutorial başlangıcında belirtilmelidir.
- 16:34Yazılım Kılavuzlarının Önemi
- Yazılım araçlarındaki tutorial kısımları, kullanıcıların o aracı kullanarak bir şey yapmaya gelmesi için önemlidir.
- Anlatılan şey bir son ürün değil, bir araç kullanarak nasıl desen çizilebileceği gibi bir kullanım kılavuzudur.
- Kılavuzda araç nasıl takılıp söküleceği, ışık yanıp yanmadığı gibi detaylar belirtilmelidir.
- 17:52Kılavuz Yazarken Dikkat Edilmesi Gerekenler
- Kılavuzda araç ucunu takarken dişin kırılmadığına, ışık yanmıyorsa elektriğin olduğundan emin olunması gibi sorunlar belirtilmelidir.
- Yazılan şey insanların aracı kullanarak çıktılar üretmesine ve araçlar geliştirmesine yardımcı olmalıdır.
- Kılavuz, bir aracın kullanım kılavuzunun ilk kullanım yönlendirme kısmı gibidir.
- 19:04Yazılım Geliştirme Kılavuzları
- "React ile önyüz uygulaması geliştirmeye hoş geldiniz" gibi bir kılavuz, kullanıcıların genel fikri bulunan ancak detayları bilmediği bir araç için yazılmalıdır.
- Drone örneğinde olduğu gibi, kullanıcılar genellikle bir yazılımın nasıl kullanılacağını bilmezler ve kılavuzdan yardım alırlar.
- React Native gibi teknolojilerde, web teknolojilerini kullanarak native standardında mobil uygulama geliştirme bilgisi verilmelidir.
- 20:56Versiyon Bağımlılıkları
- Kılavuz yazarken versiyon bağımlılıklarına dikkat edilmelidir, özellikle CS, npm gibi meselelere özen gösterilmelidir.
- Farklı versiyonlarda aynı kodun çalışmayabileceği için, kılavuzda kullanılan teknolojilerin versiyonlarına dikkat edilmelidir.
- Bazı yazılım tutorial sitelerinde, yazının bir yıldan fazla geçmişse "kullanılan teknolojilerin versiyonlarına dikkat edin" uyarısı verilir.
- 22:34İyi Bir Kılavuz Örneği
- VX ODC paketi gibi bir kılavuz, UX ve IDC gibi kavramları daha önce duymamış olabilecek kullanıcılar için zeminlik sağlar.
- Kılavuz, kullanıcıların neleri biliyor da oraya geldiğini gösterir.
- Örneğin, VX ODC paketi, Vue.js'in içinde state management için kullanılan bir araçtır.
- 23:28OpenIDConnect ve Vue.js Entegrasyonu
- OpenIDConnect, OAuth 2.0 standartını kullanarak kullanıcı giriş işlemlerini sağlayan bir pakettir.
- Vue.js ve Vuex kullanırken, Vue.js'in üstünde state management yapmak ve OpenIDConnect kullanmak isteyenler için "voxidc" adlı bir paket geliştirilmiştir.
- Bu paket, Vue.js, Vuex ve OpenIDConnect'in gereksinimlerini bir araya getirerek kullanılabilecek bir çözüm sunmaktadır.
- 24:33Paket Kurulumu ve Referanslar
- Paketin belgesi, kullanıcıların Vue.js, Vuex ve OpenIDConnect'i biliyor olmalarını varsayarak hazırlanmıştır.
- Paket, npm paketi olarak mevcuttur ve OpenIDConnect client'ın üstüne geliştirilmiştir.
- Paketin kendi deposunda çalışan bir örneği bulunmakta ve ayrıca Noxt üzerinde single page application geliştirme örneği de mevcuttur.
- 26:20Kurulum ve Kullanım
- Kurulum için öncelikle OpenIDConnect client ayarları oluşturulmalıdır.
- Vue.js'te Vuex objesi oluşturulurken, voxidc paketi modül olarak eklenmelidir.
- OpenIDConnect'in callback'inin çalışacağı rota tanımlanmalıdır.
- 28:51Vue Router Entegrasyonu
- Vue Router kullanıyorsanız, beforeEach middleware tanımlaması yapılabilir.
- Vue Router'ın beforeEach middleware'ına voxidc paketi import edilerek entegrasyon sağlanabilir.
- Standart komponentlerin render edilmesini yönlendirmek için de benzer bir yaklaşım kullanılabilir.
- 30:26Paket Özellikleri ve Kullanım Örnekleri
- Paket, kullanıcı girişi yapılmış mı, mevcut authentication token'ı ve yenileme token'ı gibi bilgileri okuma imkanı sağlar.
- Yetkilendirmeye sahip olup olmadığınızı kontrol etmek için örnek bir component sunulmuştur.
- API talebi atmak için token'ı okuma işlemi de tutorial içinde gösterilmiştir.
- 32:20Ek Özellikler ve Ayarlar
- Giriş yapmış olan kullanıcının bilgisini okuma ve çıkış yapma işlemleri için get ve action'lar bulunmaktadır.
- View Router'ın içindeki meta bölümüne "isPublic" true ekleyerek rotayı dışarıya açık tutabilirsiniz.
- OpenIDConnect'te OAuth 2.0 standartlarında token'ın son kullanım süresi vardır ve bu süre dolmadan önce yenileme tokenı ile yenileme işlemi yapılabilir.
- 34:08Paket Özellikleri ve API
- Component ekrandan silinirken event listener'ı dinlemeyi unutmamak gerekir.
- Paketin tüm özellikleri tek tek ihtiyaç duyulabileceği sırayla tutorial şeklinde gösterilmiştir.
- Paketin API'si (Application Programming Interface) kullanıcı girişi, token okuma, giriş ve çıkış işlemleri için örneklerle anlatılmıştır.
- 34:51Component Kullanımı
- Paketin API'si sadece liste olarak değil, ihtiyac duyulduğunda kopyalayıp yapıştırılabilen tam bir component halinde sunulmaktadır.
- Kullanıcı erişim token'ı, dolacağı zamanı, id token'ı ve yenileme token'ı gibi bilgiler okunabilir.
- "Has access" hesaplanmış veri, kullanıcı yetkilendirildi mi veya ziyaret edilen rotanın public olup olmadığına göre erişim durumunu belirtir.
- 36:29Kurulum ve Kullanım
- Paketin kurulumu için npm referansı ve ayar dosyası oluşturulması gösterilmiştir.
- Store kurulurken modül kısmına paket sızdırılarak eklenmesi ve giriş işleminde callback kullanımı anlatılmıştır.
- Rota tanımlama ve middleware ekleme için gerekli adımlar bir bütün olarak yönlendirilmiştir.
- 38:23Optional Aşamalar ve Tekrar
- Paket belgesinde her aşamada baştan aşağı bir komponent verilmesi, özellikle "optional" olarak belirtilen aşamalar için önemlidir.
- Optional aşamalar atlanabilir, bu nedenle her aşamada gerekli bilgilerin tekrar verilmesi gerekir.
- Yazılımda kendinizi tekrar etmekten kaçınmanız gerekir, ancak öğretim belgesinde tekrar etmekten korkmayın.
- 40:49Kullanım Çeşitlilikleri ve Kapanış
- Paket belgesinde kullanım çeşitlilikleri, okuyucuyla etkileşim ve action tetikleme gibi tüm seçenekler listelenmiştir.
- Hem paket belgesi hem tutorial şeklinde ilerleyen bu belge, özgür yazılımın güzelliğini göstermektedir.
- Sunum sonunda izleyicilere teşekkür edilmiş ve sonraki etkinliklerde görüşmek üzere veda edilmiştir.