Söz uçar yazı kalır.
Projeye başladığımızda çoğu zaman önceliğimiz teknik konular oluyor. Şu framework’ü mü kullansak, şu mimari mi olsa, bu pattern mi olsa vb. Ya da doğrudan süreçleri kodlamaya odaklanıyoruz.
Atalarımız ne güzel söylemişler “söz uçar yazı kalır” diye. Geliştirmeler yapılırken bir sürü iş yapıyoruz. Parametreler ekliyoruz, konfigürasyonlar yapıyoruz, bir utility geliştiriyoruz. Fakat çoğu zaman bu yaptıklarımızın genel bilgisi yapan kişide kalıyor. Bir şekilde bakım yapmak gerektiğinde tekrardan kodları okuyup anlayarak çözüm bulmaya çalışıyoruz. Ya da var olan birşeyi tekrardan yaptığımız da oluyor.
Peki bu yaptıklarımızı dokümante etsek! Dokümantasyon bize ne sağlar,
- En başta projenin bir büyük resmini çizer. Geri dönüp bakıldığında neler yapılmış, nasıl bir mimari kurgulanmış, ne gibi standartlar var vb. Birçok konuda proje hakkında fikir verir.
- Projeye yeni dahil olan birisinin hızlı adapte olmasını sağlar
- Projedeki standartları belirlememizi sağlar
- Geliştirilmiş tool’ların ne ve nasıllarını görmemizi sağlar
- Projenin belirli kurallara göre geliştirildiğini/bakımının yapıldığını gösterir.
- Standartlaşmayı sağlar
Bunlar gibi birçok şey söyleyebiliriz. Evet doküman yazalım fakat bazen buna nasıl başlayacağımızı bilemeyebiliyoruz. Ya da bu dokümanın içerisinde ne gibi başlıkların olması gerektiğini belirlemekte zorlanabiliyoruz. Ya da bu dokümanı nasıl bir araç ile yazacağımızı bilemeyebiliyoruz. Word, excel gibi araçlar ile teknik dokümantasyon yazılmaya çalışıldığını gördüm. Açıkca söylemeliyim ki teknik konular için office araçlarını kişisel olarak sevmiyorum. Hep bende “ya yazalım verelim şu dokümanı, kurtulalım” hissiyatı ile yazıldığını hissettiriyor.
Bu noktada sizlere MkDocs aracını önerebilirim. MkDocs markdown formatında dokümanlar yazmamızı sağlıyor. Yazılan dokümanları static web sitesi olarak export ediyor. Bunun yanında tema desteği sağlıyor, export edilen web sitesinin temasını değiştirebiliyorsunuz. Ayrıca PDF gibi farklı formatlara da export edebiliyorsunuz.
MkDocs python ile geliştirilmiş bir araç bu sebepten python kurulumuna ihtiyacınız olacak.
Peki dokümantasyon içerisinde hangi başlıklar olabilir. fikir vermesi açısından kabaca aşağıdaki gibi olabilir;
- Projenin genel tanıtımı
- Mimari
- Backend/Frontend teknolojileri
- Kod organizasyonu; paket yapıları
- Geliştirme standartları, yazım stilleri
- Geliştirilen library’lerin özellikleri ve nasıl kullanılacağı
- Deployment süreçleri
Buradaki başlıklar gibi ihtiyacınıza göre bunları çeşitlendirebilirsiniz.
Kurulum
pip3 install mkdocs
Örnek proje oluşturma ve çalıştırma
python3 -m mkdocs new my-project pip3 install mkdocs-material #metarial tema kurulumu için cd my-project set/export ENABLE_PDF_EXPORT=0s python3 -m mkdocs serve --dev-addr=localhost:9003
Static Web Site olarak export etme
python3 -m mkdocs build
ve sonuç…
Proje oluştuktan sonra bir dosya ve bir dizin oluşmakta.
“mkdocs.yml” dosyası menü ağacını yazmamızı sağlamakta.
Detayları incelemeniz için örnek bir proje oluşturdum buradan erişebilirsiniz.