VuePress: Belgeleme Kolaylaştı

Herhangi bir kullanıcı etkileşimi gerektiren herhangi bir proje söz konusu olduğunda (örneğin, son kullanıcılar, bakımcılar, vb.), başarı ile başarısızlık arasındaki farkı yaratan kritik bir faktör vardır: iyi dokümantasyon. Bu, projenizin ne kadar küçük veya büyük olduğuna bakılmaksızın geçerlidir. Sonuçta, projeniz için bire bir destek sağlamanın dışında, bir sorunu çözmeye çalışan kullanıcılar için dokümantasyon ilk savunma hattıdır. Ve beğenseniz de beğenmeseniz de, yetersiz dokümantasyon nedeniyle sorununu çözemedikten sonra vazgeçen kullanıcılardan asla haber almayacaksınız.

İyi Dokümantasyon Oluşturmanın Zorlukları

Konu iyi dokümantasyon yazmaya geldiğinde, ekiplerin sıklıkla karşılaştığı, tekrar eden dört sorun vardır:

1. Belgeler genellikle güncelliğini yitirir.
   Bir proje için hiçbir dokümantasyon sinir bozucu bir deneyim olmasa da, eski dokümantasyona sahip olmak tartışmasız daha kötüdür. Sonuçta, belgelere sahip olmanın amacı, kullanıcılara güvenebilecekleri resmi bir bilgi birikimi sağlamaktır. Güncel olmadığında, kullanıcılar zamanlarını boşa harcıyor ve nihayetinde ürününüze olan güvenlerini kaybediyorlar.
   
   Belgelerin güncelliğini yitirmesinin başlıca nedeni, belge bakımının kod değişikliklerinden ayrı olmasıdır . Önemli ölçüde zaman ve enerji harcamadan bunu çözmek zor olabilir çünkü:
   
   1. Belgeler genellikle Confluence veya Wiki gibi bir üçüncü taraf hizmetinde bulunur,
   2. Geliştiriciler genellikle dokümantasyondan çok kod yazmakla ilgilenirler.
2. Kullanıcılar kolayca geri bildirim sağlayamazlar.
   Belgelerinizin ne kadar iyi olduğunu düşünürseniz düşünün, geri bildirim sağlayabilecek gerçek kullanıcılarla test etmeden sonuç olarak anlamsızdır. Daha önce de belirtildiği gibi, dokümantasyon gibi şeylerin etkinliğini değerlendirirken yaygın bir önyargı, sorunlarını çözemeyen ve vazgeçen kullanıcıları hesaba katmamaktır. Hiçbir ekip, kullanıcıların ürününüzü nasıl kullanabileceğine dair her senaryoyu hesaba katamayacağından, kullanıcıların geri bildirimde bulunmak için kolay ve güvenilir bir yolu olmalıdır.
3. Belgeler genellikle uzman kullanıcılar tarafından uzman kullanıcılar için yazılır.
   Wiki'ler veya BENİOKU dosyaları gibi standart araçları kullanmanın kusuru, bunların genellikle yalnızca önceden var olan kitaplık ve/veya teknoloji yığını bilgisine sahip belirli bir kullanıcı grubuna hitap etmesidir. Sonuç olarak, uzayda gezinmeleri ve ihtiyaç duydukları şeyi bulmaları oldukça basittir. Bununla birlikte, yeni kullanıcılar bu ön bilgiden yoksundur ve bu nedenle, onlarla etkileşim kurmak için genellikle çok daha sürükleyici bir deneyim gerektirir.
   
   Bunun örnekleri şunları içerir:
   
   • İyi tasarlanmış bir web sitesi,
   • Arama yeteneği,
   • Kılavuzlu yan navigasyon,
   • Kolayca tanımlanabilen meta bilgiler (yani, son güncelleme tarihi),
   • Kolayca anlaşılması zor bir metin duvarının ötesine geçen sürükleyici içerik.
4. Belgelerin bakımını zorlaştıran zayıf altyapı.
   Kullanıcıların anlayabileceği iyi belgeler yazmak yeterince zor değilmiş gibi, bir geliştiricinin belge yazma ve/veya koruma kolaylığı, uzun vadeli uygulanabilirliği için kritik öneme sahiptir. Bu nedenle, geliştiricilerin belge yazmak ve/veya sürdürmek için uğraşması gereken her ek engel için, sonuçta başarısız olma olasılığı daha yüksektir. Sonuç olarak, herhangi bir belgenin yazma deneyiminin ve bakımının mümkün olduğunca sorunsuz ve ilgi çekici olması çok önemlidir.

Keşke tüm bunları bizim için yapabilecek bir araç olsaydı…

VuePress'e girin

VuePress'i ilk duyduğunuzda, bunun Vue.js ve WordPress'in bir birleşimi olduğunu tahmin etmek cazip gelebilir. Bunun yerine, VuePress'i şu şekilde düşünmelisiniz:

Vue.js + Matbaa

Çünkü her şey söylenip yapıldığında, VuePress statik bir site oluşturucudur!

Bazılarınız, “Bekle. Başka bir statik site oluşturucu mu? Problem ne?"

Statik site oluşturucular olan bir dizi araç olsa da, VuePress paket arasında tek bir nedenden dolayı öne çıkıyor: birincil yönergesi, geliştiricilerin projeleri için harika belgeler oluşturmasını ve sürdürmesini kolaylaştırmaktır.

VuePress Dokümantasyon Oluşturmak İçin Neden Bu Kadar Güçlü?

Cevap basit. Tek bir amaç düşünülerek tasarlandı: geliştiricilerin eğlenceli bir yazma deneyimi sağlarken harika belge siteleri oluşturmalarına yardımcı olmak. Bu, geliştiriciler için bir çerçeve sağladığı anlamına gelir:

• Güzel dokümantasyon siteleri oluşturun,
• Tüm dokümantasyon siteleri için gerekli olan önceden oluşturulmuş özelliklerle gelin,
• Bir Markdown dosyasını güncellemek kadar basit hale getirmek için yazma deneyimini optimize edin.

VuePress Mevcut Kod Tabanınızla Birlikte Var Olabilir

Şiddetle tavsiye etmemin ana nedenlerinden biri de bu. Belgelerin bakımı söz konusu olduğunda, bunların güncelliğini yitireceğini garanti etmenin bir yolu, geliştiricilerin kod yazarken belgeleri güncellemelerini zorlaştırmaktır. Geliştiricileri şeyleri iki farklı yerde güncellemeye zorlayarak yazma deneyimini zorlaştırırsanız, bu çok fazla sürtüşmeye neden olur ve çoğu zaman belgelerin yol kenarına bırakılmasına neden olur. Bu, geliştiricilerin kod tabanının kendisine ek olarak wiki gibi bir üçüncü taraf aracı bulundurması gerektiğinde yaygın olarak görülür.

Statik bir site oluşturucu olduğundan, bu, kodunuzla aynı depoda yaşayabileceği anlamına gelir.

Bu örnek web uygulaması yapısında görebileceğiniz gibi, kodunuz normal olarak src dizininde bulunur, ancak tüm belgelerinizi içeren bir docs dizininiz olur. Bu, şu avantajları elde ettiğiniz anlamına gelir:

• Tüm belgeler artık sürüm kontrollüdür;
• Çekme istekleri artık hem belgeleri hem de kod değişikliklerini içerebilir;
• Kodunuzun ve belgelerinizin yerel örneklerini aynı anda çalıştırmak için ayrı komut dosyaları oluşturma;
• Yeni belge sitesi dağıtımlarının kod dağıtımlarıyla senkronize olup olmadığını belirlemek için derleme işlem hatlarını kullanın.

Varsayılan Tema, Standart Yapılandırmayla Birlikte Gelir

Belge yazmak, olduğu gibi yeterince zordur, bu nedenle VuePress, normalde yapılması gereken birçok kararı devre dışı bırakır ve yazma deneyiminizi kolaylaştırmak için bir dizi yerleşik varsayılana sahiptir:

• İçerik yazma, öncelikle Markdown ile yapılır.
  Bu, metninizi biçimlendirmek ve biçimlendirmek için mevcut Markdown sözdizimi bilginizden yararlanabileceğiniz anlamına gelir.

• Kod sözdizimi vurgulama.
  Tamamen kendi başınıza bir site oluşturuyorsanız, renk sözdizimi vurgulama kitaplıklarıyla boğuşmanız gerekir. Ancak şanslısınız çünkü VuePress'te kod blokları ekleyebiliyorsunuz çünkü her şey sıfır konfigürasyonla gitmeye hazır olduğundan çok kolay.

• Sayfa düzeyinde meta verileri tanımlamak için ön madde.
  Bir Markdown dosyasında yazıyor olsanız bile, içeriğinizi yönetmeyi daha da kolaylaştırmak için sayfanızın meta verilerini tanımlamak için ön maddeyi (YAML, JSON veya TOML gibi) kullanabilirsiniz!

 --- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---

• Özel Markdown kapsayıcıları.
  Bilmiyorsanız, Markdown, özel kapsayıcılar gibi güzel UI bileşenleri oluşturmak için daha da kullanışlı kısayollar eklemek için uzantılara sahiptir. Belgelemede çok yararlı olduklarından, VuePress onu kutudan çıkar çıkmaz kullanabilmeniz için zaten yapılandırmıştır:

Dahili Arama İşlevi

Kabul edelim. Harika belgeler yazmak için ne kadar zaman harcarsak harcayalım, kullanıcılar onu bulamazsa, sonuçta işe yaramaz hale gelecektir. Buna genel olarak iki yaklaşım vardır:

1. Bir gün kullanıcılarınızın sitenizde doğru sayfayı bulabileceği umuduyla, arama motoru robotlarının sitenizi yavaşça taramasını bekleyin. Harika bir çözüm değil.
2. Kendi arama işlevinizi oluşturun, ancak arama dizinleri oluşturmak ve aramaları gerçekleştirmek için çalışan sunucu tarafı kodu olmadığından statik siteler için bunu uygulamak zor olabilir. Bunun ürünün kendisinden geliştirme zamanını aldığını söylemeye gerek yok. Yani bu da harika değil.

Şansımıza, VuePress bir kez daha günü kurtarmak için burada!

VuePress, kendi "arama motorunu" oluşturan yerleşik bir arama işleviyle birlikte gelir - doğru okudunuz. Herhangi bir ek veritabanı kurulumu veya yapılandırması olmadan, VuePress, tüm h1'lerinizi ve h2'lerinizi kullanıcınıza gösterecek basit bir arama motoru oluşturmak için tüm belgelerinizi sıyıracak şekilde ayarlanmıştır.

Şimdi, bazılarınız şöyle düşünüyor olabilir,

"Ya arama için daha düşük düzeyde indeksleme sağlayacak bir şey istersem?"

Peki, VuePress sizi orada da ele aldı çünkü gereksinimlerini karşılarsanız bu işlevi size ücretsiz olarak sağlayabilen Algolia DocSearch ile kolayca entegre olacak şekilde tasarlanmıştır:

Kenar Çubuğunda Gezinme Özelliği Açmak veya Kapatmak Kadar Basittir

İçeriği yönetmekten sorumlu olan herkes için, iç içe öğeler içeren bir kenar çubuğu oluşturmanın ve ardından aşağı kaydırırken okuyucunun hangi konumda olduğunu izlemenin ne kadar karmaşık olabileceğini bilirsiniz. Öyleyse neden daha iyi dokümanlar yazabilecekken buna zaman harcıyorsun? VuePress ile kenar çubuğu, bir sayfanın ön maddesini değiştirmek kadar basittir:

Genellikle Gözden Geçirilen Önemli Meta Verilerin Otomatik Olarak Oluşturulması

Bir kullanıcının karşılaşabileceği en sinir bozucu şeylerden biri, güncel olmayan belgelerdir. Bir kullanıcı adımları izlediğinde ve bir şeyin neden çalışmadığını anlamakta güçlük çektiğinde, son güncelleme tarihini kolayca öğrenebilmek hem kullanıcı hem de projenin sahipleri için inanılmaz derecede faydalı olabilir.

Basit bir yapılandırmayla, VuePress, kullanıcılarınızın her zaman en son ne zaman güncellendiğini bilmeleri için sayfadaki son güncelleme tarihinin otomatik olarak çıktısını sağlayabilir.

Bunun da ötesinde, biraz yapılandırma ile VuePress, kullanıcıların belgelerinize kolayca bir çekme isteği oluşturmasına olanak tanıyan her sayfanın altında otomatik olarak bir bağlantı oluşturarak kullanıcıların belgelerinize katkıda bulunmalarını inanılmaz derecede kolaylaştırır.

Kullanıcılarınız için bundan daha kolay olamaz.

Herhangi Bir Statik Barındırma Sitesinde Dağıtım

VuePress özünde statik bir site oluşturucu olduğundan, bu, onu aşağıdakiler gibi herhangi bir popüler barındırma platformuna dağıtabileceğiniz anlamına gelir:

• netleştir
• GitHub Sayfaları
• GitLab Sayfaları
• Heroku
• Şimdi

Siteyi oluşturmak için yapmanız gereken tek şey, dizininizin bulunduğu yerde vuepress build {{ docsDir }} çalıştırmak ve onu web'de canlı olarak dağıtmak için ihtiyacınız olan her şeye sahip olacaksınız!

Not : Bunun nasıl yapılacağına ilişkin daha ayrıntılı kılavuzlar için VuePress için resmi dağıtım kılavuzlarına bakın.

Markdown Dosyanızın İçinde Vue'dan Yararlanma

Biliyorum biliyorum. Vue.js'yi Markdown'ımızda kullanabilir miyiz?! Evet, doğru okudunuz! Teknik olarak isteğe bağlı olsa da, bu muhtemelen VuePress'in en heyecan verici yönlerinden biridir çünkü Markdown içeriğinizi daha önce hiç yapamadığınız şekilde geliştirmenize olanak tanır.

Tekrarlayan Verileri Tek Bir Yerde Tanımlayın ve İnterpolasyon ile Her Yerde Güncellenmesini Sağlayın

Aşağıdaki örnekte, yerel değişkenleri (ön maddede tanımlananlar gibi) ve küresel olarak tanımlanmış olanları (site başlığı gibi) nasıl kullanabileceğinize dair kısa bir örnek göreceksiniz:

 --- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!

Markdown İçinde Vue Bileşenlerini Kullanın

Bunu okuduktan sonra kendinizi toplamanız için size biraz zaman vereceğim, ancak evet, isterseniz tam bir Vue örneğine sahip canlı Vue bileşenleri almak için sizin olabilir! Konfigüre etmek biraz daha fazla çalışma gerektirecektir, ancak dokümantasyonunuzda çalışacak özel içerik oluşturduğunuzdan bu beklenebilir.

İşte bir Markdown dosyasında bir Counter bileşeninin nasıl görüneceğine dair hızlı bir örnek:

Bu belki de belgeler için mevcut olan özelleştirmenin en güçlü kısmıdır, çünkü artık standart Markdown'ın yeteneklerinin çok ötesine uzanan özel içerik oluşturma özgürlüğüne sahip olduğunuz anlamına gelir. Yani ister bir demo, isterse bazı etkileşimli kodlar sağlıyor olsun, fikirler sonsuzdur!

Sonraki adımlar

Kullanıcılarınızın ürününüzü nasıl kullanacaklarını öğrenmeleri için güzel bir dokümantasyon sitesi kurmak istiyorsanız, VuePress'ten daha kolay olamaz. VuePress'in yalnızca Vue.js kullanan projeler tarafından kullanılması gerektiğini varsaymak kolay olsa da, bu gerçeklerden daha fazla olamaz. Belgeleme siteleri için VuePress'ten yararlanan farklı proje türlerine ilişkin bazı örnekler:

• Craft CMS
• UmiJS (React için oluşturulmuştur)
• açık HAB
• tavuskuşu

Günün sonunda, VuePress kullanıp kullanmadığınıza bakılmaksızın, umarım bu, kullanıcılarınız için daha iyi belgeler oluşturmanız için size ilham vermesine yardımcı olmuştur.

Diğer Kaynaklar

Bu makalede burada değinmediğim pek çok harika şey var (örn. tema oluşturma, blog oluşturma vb.), ancak daha fazlasını öğrenmek istiyorsanız şu kaynaklara göz atın:

• Resmi VuePress Belgeleri
• VuePress İle İlgili Kaynakların Seçilmiş Listesi
• VuePress Galerisi
• VuePress Blogu