TechDocs, markdown dosyalarını bir depoda bulunduktan sonra, bu belgeleri Backstage instance’ınızda yayınlanacak sayfalara dönüştürmek için üç aşamadan geçer: hazırlık, üretim ve yayına alma. Bu süreç, belgelerinizi kolayca yönetmek ve sunmak için etkili bir yol sunar. Ancak üretim ortamlarında daha dikkatli yaklaşılması gereken bazı noktalar da vardır.
Hazırlık Aşaması
İlk aşama, TechDocs’un component’in deposunu geçici bir dizine kopyalayarak belgeleri yerel olarak erişilebilir hale getirmesidir. Bu sayede belgelerin doğru şekilde oluşturulması için gerekli kaynaklara erişim sağlanır. Hazırlık aşaması, belgelerin oluşturulmasından önce gerekli tüm dosyaların toplanmasını sağlar.
Üretim Aşaması
Üretim aşamasında, TechDocs, mkdocs-techdocs-core adlı bir Docker görüntüsünü kullanarak statik varlıkları oluşturur. Bu Docker görüntüsü, Python kütüphanesi aracılığıyla belgeleri oluşturan ve statik varlıkları derleyen süreci yönetir. Buradaki önemli nokta, belgelerin statik olarak üretilmesi ve her seferinde dinamik olarak oluşturulması gerektiğinde karşılaşılan zorluklardır.
Yayına Alma Aşaması
Son aşama, oluşturulan statik varlıkların uygun bir yere taşınarak dağıtıma sunulmasıdır. TechDocs, belgeleri düzgün bir şekilde yayımlamak için bu varlıkları depolamak ve erişilebilir hale getirmek için uygun bir yöntem gerektirir.
Üretim Ortamlarındaki Zorluklar
Yukarıda açıklanan süreç, başlamak için oldukça basit görünse de, üretim ortamında bazı sınırlamaları vardır. Örneğin, belgelerin oluşturulması için Docker görüntüsünün kullanılması, bu sürecin Kubernetes podlarında çalıştırılmasını zorlaştırabilir. Dockerfile’ınıza Backstage dışı bağımlılıklar eklemek istemiyorsanız, görüntü ikili dosyalarını kullanmak bir seçenek olabilir, ancak bu da sistemin karmaşıklığını artırır.
Ek olarak, belgeleri anında oluşturmak, ilk taleplerde yavaşlamaya ve birden fazla backend yapılandırmasına sahip olduğunuzda tekrarlanan iş yüklerine yol açabilir. Her bir backend için belgelerin yeniden oluşturulması gerektiğinden, kaynak kodunun her seferinde çekilmesi güvenlik beklentilerinizi karşılamayabilir.
Dış Kaynaklarla Belgeleri Yayınlama
Bu nedenlerden dolayı, TechDocs’u dahili üretimden çıkarmayı tercih edebilirsiniz. Bunun için TechDocs annotation’ında techdocs.builder değerini external olarak belirleyebilir ve belgeleri bir bulut depolama alanında yayınlayabilirsiniz. Genellikle, CI sisteminizi kullanarak belgelerinizi oluşturabilir ve bir Pull Request (PR) birleştiğinde otomatik olarak bu belgeleri oluşturabilirsiniz. Daha sonra, oluşturulan varlıklar bir Cloud Storage’a, örneğin bir S3 Bucket’a yayınlanır ve Backstage instance’ınız gerekli olduğunda bu belgeleri okur.
TechDocs Mimarisi
TechDocs’un mimarisi, belge oluşturma sürecini çok daha verimli ve ölçeklenebilir hale getirmeyi amaçlar. Bu mimari, Backstage Software Catalog ve Developer Platform’da entegre bir şekilde çalışarak, geliştiricilerin kolayca erişebileceği ve güncelleyebileceği bir belge yönetim sistemi sunar.
TechDocs Yazma
TechDocs, MkDocs’u kullanarak belgelerinizi oluşturur ve Material for MkDocs stilini kullanarak stilize eder. Bu, belgelerinizi yazarken Backstage ile ilgili özel bir gereksinim olmadığı anlamına gelir. Markdown dosyalarınızı ve konfigürasyonlarınızı yazarken, MkDocs’la genellikle kullandığınız yolları takip edebilirsiniz.
Yazma aşamasında, standart markdown kullanabilirsiniz. Üretim sürecini yöneten Python kütüphanesi, standart markdown sözdizimi ile uyumludur ve çok küçük farklar dışında herhangi bir farklılık bulunmaz. Belgelerinizdeki dosyaları bağlarken, standart relatif markdown bağlantıları kullanabilirsiniz.
Sonuç
TechDocs, yazılım geliştirme süreçlerinde dökümantasyonun oluşturulması ve yayına alınması için güçlü bir araçtır. Ancak, üretim ortamlarına geçmeden önce sürecin bazı kısımlarını dışsallaştırarak daha verimli bir hale getirmek önemlidir. Bu sayede, belgelerinizin doğru ve güvenli bir şekilde oluşturulmasını sağlayarak, organizasyon içindeki herkesin ihtiyaç duyduğu bilgilere kolayca erişmesini mümkün kılabilirsiniz.