Kod yazarak yapacaklarimizi kesfettikten sonra dokumantasyon yazmak zul gelebiliyor. Aslinda dokumantasyonda kod yazmak kadar onemli bir rol oynuyor .
Dokumantasyon neden onemli?
Bunu yapmayi sevdiginiz ve iyi bildiginiz bir yemegin tarifini vermek gibi dusunebilirsiniz. Sadece malzemeleri verir ve tarifi vermezseniz baskalarinin yemeginize katkida bulunmasini ve nasil yapildigini anlamasini beklemek biraz mucize gibi olabilir 🙂 Bu noktada yazdigimiz kodu takim calismasina acmak ya da bir proje icin bizden sonra calisacak olanlara yol gostermek icin dokumanasyon yazmak oldukca onemli bir konu halini aliyor.
Hele ki acik kaynak destekliyor ve katki saglamak istiyorsaniz iyi dokumantasyon oldukca onemli bir konu halini aliyor. Eger iyi bir dokumantasyonunuz olursa insanlar sizin yaziiginiz kutuphaneyi kullanmak isteyecektir
Dokumantasyon yazarken ilk aklimizda bulundurmamiz gereken konu ise :
Dokumantasyon insanlarin okumasi icin, makinelerin degil 🙂
Ozellikle 3.parti kutuphanelerde ozellikle onem tasiyor. Bazen sadece dokmantasonu icin kullanmaktan vazgecilen kutuphaneler olabiliyor.
Read me dosyasinin yazilisi cogunlukla gelistiriciye bagli olsa da temel olan conseptleri gozetmekte fayda var. Bunlarin ilki Lisanslama olayi, Sizi ve projenizi en iyi ifade edecek lisansi buradan http://choosealicense.com secebilirsiniz. (ISterseniz kensiniz de yazabilirsiniz 🙂 )
Ikinci adimda eger projenize katkida bulunulsun istiyorsaniz(contributing) bunun yonlendirmesini de read me dosyasinizda yapabilirsiniz.
Bununla birlikte read me dosyasi duzgun olsun derken ihtiyacinizdan fazla seyler yazmanize ya da bunun icin endiselenmenize gerek yok, code unuz sekillendikce read me file de sekillencektir 🙂 yeri ve ihtiyaci geldikce bolum bolum eklemeler yapablirsiniz. Bu eklemelerin icerisine buglariniz (aksi halde kullanicilar hatayi kendilerinde arayabilirler), surekli ayni soruyu aliyorsaniz sik sorulan sorular , icindekiler bolumu.
Readable Readmes With Markdown
Read me dosyasini istediginiz formatta yazabilirsiniz. Web sayfasi, basit bir text dosyasi ya da istediginiz gibi formatladirmak elinizde. Developerlar olarak oldukca fazla tercih edilen bir yontem olan markdown var.
Markdown read me yazmak icin yayginca kullanilan bir markup language. Tabi k markdowunun da farkli bicimleri var. Bunu daha cok farkli yorelerin farkli siveleri olmasina benzetebiliriz. 🙂 Takip etmesi kolay oldugu icin GitHub Flavored Markdown tercihim.
- mukemmel bold icin.
- talk is cheap, show me the code! italik icin
console.log('kod icin'):
kod icin- ## bunlar ise basliklar icin
Daha fazlasi icin hemen buraya goz atabilirsiniz :
Markdowninizi goruntulemek isterseniz de burayi kullanabilrisiniz (suan link calismiyor sebebini anlayamadim) ya da burayi. Ya da sublime text kullaniyorsaniz guzel bir plugin mevcut!