Dokümantasyon, yazılım geliştirme döngüsünün önemli bir parçasıdır. Yazılımın nasıl kullanılacağını açıklar ve kullanıcı kılavuzlarını, API referanslarını, yükleme talimatlarını ve sürüm notlarını içerebilir.
Belgelerinizi otomatikleştirmek, zamandan tasarruf etmenize, hataları azaltmanıza ve tutarlılığı sağlamanıza yardımcı olabileceği için en son trend. Belgelerinizi güncel ve tüm paydaşlar için erişilebilir tutmak, işbirliğini ve sürekli iyileştirmeyi kolaylaştırır.
Docs as code, teknik dokümantasyonu kod olarak ele alan bir dokümantasyon otomasyonu yaklaşımıdır.
Dokümanlar Kod Olarak Nedir?
Kod olarak belgeler, teknik belgeleri bir kod biçimi olarak gören bir yazılım geliştirme felsefesidir. Dokümantasyona yazılım koduyla aynı titizlikle ve süreçle yaklaşmanız gerektiğini önerir.
Dokümanların kod olarak arkasındaki fikir, dokümantasyonu yazılım yaşam döngüsüyle entegre ederek geliştirme sürecinin birinci sınıf bir ürünü olarak ele almaktır. Bu, belgeleri kod tabanının ayrılmaz bir parçası olarak ele almak anlamına gelir. Bu, kodun kendisine uyguladığınız sürüm kontrolünün, sürekli tümleştirmenin ve test süreçlerinin aynısını ona uygulamak anlamına gelir.
Kod kurulumu olarak tipik bir dokümanda, dokümantasyonu düz metin dosyalarına yazarsınız, genellikle Markdown gibi hafif bir biçimlendirme dili, HTML veya reStructuredText. Daha sonra kaynak kodla aynı depoda saklarsınız. Bu, hem yazılım hem de belgelerdeki değişiklikleri yönetmeyi ve izlemeyi kolaylaştırır. Ayrıca, belgelerin kodun en son sürümüyle güncel olmasını sağlamaya yardımcı olur.
Dokümanları Kod Olarak Neden Kullanmalısınız?
Dokümanlar kod olarak kullanılmadan önce, dokümantasyon genellikle farklı araçlar ve süreçlerle oluşturulan koddan ayrı olarak ele alınıyordu. Bu daha gevşek yaklaşım, genellikle eski belgelere ve kodla tutarsızlıklara yol açtı. Dokümanları kod yaklaşımı olarak benimseyerek çeşitli avantajlardan yararlanabilirsiniz.
Geliştirilmiş İşbirliği
Docs as code, geliştirme sürecindeki geliştiriciler, teknik yazarlar ve diğer paydaşlar arasında işbirliğine olanak tanır. Kod deposu belgeleri barındırdığından, farklı tarafların katkıda bulunması ve değişiklik yapması kolaydır. Bu, belgelerin doğru, güncel ve kapsamlı olmasını sağlamaya yardımcı olur.
Dokümantasyona işbirlikçi bir yaklaşım, ilgili tüm bilgileri içermesini ve tüm taraflarca yorumlandığı şekliyle yazılım sistemini doğru bir şekilde yansıtmasını sağlamaya yardımcı olur.
Süreç Otomasyonu ve Erişilebilirlik
Dokümanların kod olarak kullanılmasının bir başka avantajı da, dokümantasyon oluşturmak ve yayınlamak için otomatikleştirilmiş araçlara olanak sağlamasıdır. Bir derleme sistemi, bir web sitesine veya dahili bir belge portalına yayınlamak üzere düz metin dosyalarından belgelerin HTML veya PDF sürümlerini otomatik olarak oluşturabilir. Bu, belgeleri daha fazla paydaş için erişilebilir hale getirir.
Dokümantasyon oluşturma ve yayınlama sürecini otomatikleştirerek, kod olarak dokümanlar, dokümantasyonu sürdürmek ve yayınlamak için gereken zaman ve çabayı azaltmaya yardımcı olur. Geliştirme ekiplerinin yazılımı iyileştirmeye odaklanmasını sağlar.
Sürüm Kontrolü
Belgelerin yazılımla aynı kod havuzunda saklanması, her ikisinde de yapılan değişiklikleri yönetmeyi ve izlemeyi kolaylaştırır.
Kullanabilirsiniz sürüm kontrol sistemleri Dokümantasyon değişikliklerini izlemek ve gerekirse önceki sürümlere geri dönmek için Git gibi. Bu, belgelerin doğru ve güncel olmasını sağlamaya yardımcı olur ve değişiklikleri izleyebilir ve denetleyebilirsiniz.
Kod İş Akışı Olarak Tipik Dokümanlar
Tipik kod olarak dokümanlar iş akışı yazma, sürüm kontrolü, oluşturma ve barındırmayı içerir:
Yazma Süreci
Yazma işlemi, tipik bir doküman olarak kod iş akışının ilk aşamasıdır. En teknik yazarlar ve dokümantasyon mühendisleri basit MarkDown, AsciiDoc veya HTML kullanır. Belgeleri, sorunsuz bir süreç sağlayan GitBook ve Redocly gibi araçları kullanarak yazarlar.
Dokümantasyon için Sürüm Kontrolü
Dokümantasyon, kod geliştikçe gelişir. Daha kolay işbirliği ve sürüm takibi için belge değişikliklerini izlemek üzere Git, Plastic SCM veya Subversion gibi gelişmiş bir sürüm kontrol sistemine ihtiyacınız olacak.
Dokümantasyon Oluşturma Süreci
Oluşturma süreci, belgelerin işlenmesini ve teslimat biçimlerine göre derlenmesini içerir. Bunlar HTML, PDF, EPUB veya diğerleri olabilir. Dokümantasyon süreci genellikle Hugo ve Jekyll gibi statik site oluşturucular kullanılarak kolaylaştırılır.
Belgeleri Barındırma ve Dağıtma
Barındırma veya dağıtım işlemi, genellikle bir kodlama işlemi olarak dokümanların son adımıdır. Bu süreç, dokümantasyonun son kullanıcıya teslim edilmesini ve tüm paydaşların kullanımına sunulmasını sağlar. Belgelerinizi web üzerinde dağıtmak için GitHub veya GitLab sayfaları ya da özel bir portal kullanabilirsiniz.
GoDoc ve JavaDoc Kullanarak Go ve Java Belgelerini Otomatikleştirebilirsiniz
Docs as code felsefesi, teknik dokümantasyon yazımı ve yönetiminde devrim yaratıyor.
Go ve Java da dahil olmak üzere birçok programlama dili, kod yorumlarını kullanarak dokümantasyonu otomatikleştirmek için araçlar sağlar. Go, Godoc aracını sağlar ve Java, JavaDoc aracını sağlar.