Teknik uzmanlık gerektirmeden ürün dokümantasyon sürecinizi düzene sokmak mı istiyorsunuz? Apidog, ürün yöneticileri ve operasyon ekiplerinin profesyonel dokümantasyon oluşturma, yönetme ve yayınlama konularında sorunsuz bir şekilde iş birliği yapmalarını sağlayan kapsamlı bir çözüm sunar. Sezgisel arayüzü, gerçek zamanlı iş birliği özellikleri ve sıfır bakım gerektiren yayınlama özelliğiyle Apidog, ekiplerin dokümantasyon iş akışlarına yaklaşımını dönüştürüyor.
Her ürünün kendi dokümantasyonuna ihtiyacı vardır. Ürününüz çok sezgisel ve basit bir etkileşim tasarımına sahip, tüketiciye yönelik bir uygulama olsa bile, daha fazla açıklama gerektiren ancak doğrudan ürün arayüzünde sunulması halinde karmaşıklık yaratacak alanlar olacaktır. Bu nedenle, doküman yönetimi, bakımı ve yayınlanması her ürün için kritik öneme sahiptir.
Ürün dokümantasyonu oluştururken, ekipler genellikle Notion gibi hazır dokümantasyon araçlarını veya Confluence ve CMS gibi içerik yönetim araçlarını ya da Docusaurus ve Gitbook gibi dokümantasyon oluşturucuları kullanır. Ancak, bu çözümler genellikle aşağıdaki sorunlarla karşılaşır:
- Dokümantasyon yazmak için kodlama gerektirir ve bu da yüksek maliyetlidir. Dokümantasyon yazıldıktan sonra bile, gerçek okuma deneyimi genellikle beklentilerin altında kalır;
- Dokümantasyon birden fazla rolün iş birliğini içerir, bu da sürüm yönetimini zorlaştırır ve optimizasyon önerilerini başkalarına iletmeyi güçleştirir;
- Bitmiş dokümantasyonu üretim ortamına yayınlamak ya çok basit ya da çok karmaşıktır, teknik olmayan meslektaşların üstesinden gelmekte zorlanabileceği mühendislik süreçlerini içerebilir ve hatalara yol açabilir.
Apidog ekibi daha önce dokümantasyonumuzu oluşturmak için Docusaurus'u kullanıyordu. Dokümantasyonumuz sürekli olarak yenilendikçe, yukarıda bahsedilen sorunlardan bazılarıyla biz de karşılaştık. Deneyimlerimizi ve öğrendiklerimizi özetledikten sonra çözümler geliştirdik ve bunları Apidog'a entegre ettik. Artık, Apidog ekibinin ürün dokümantasyonu tamamen Apidog'a taşındı, tüm oluşturma ve sunum Apidog tarafından yapılıyor.
Apidog aracılığıyla ürün dokümantasyonunu nasıl oluşturduğumuza dair uygulamalarımızı paylaşacağım. Bundan önce, Apidog'un ürün dokümantasyonunun belirli etkilerini daha yakından incelemek isterseniz, Apidog yardım dokümantasyonunu inceleyebilirsiniz - geri bildirimler memnuniyetle karşılanır.
Arka Plan
Uygulamalarımızı tanıtmadan önce, herkesin neden bu şekilde davrandığımızı daha iyi anlaması için öncelikle açıklanması gereken bazı bağlamlar var. Şirketimizin ürün dokümantasyonu genellikle ürün ve operasyon departmanı meslektaşları tarafından iş birliği içinde oluşturulur. Ana süreç aşağıdaki gibidir:
Yukarıdaki süreçte teknik personel katılımı gerekmez - ürün dokümantasyonuyla ilgili tüm işlemler bu iki departmandaki meslektaşlar tarafından tamamlanır. Şimdi, bu sürece göre Apidog aracılığıyla ürün dokümantasyonu oluşturma görevini nasıl tamamlayacağımızı açıklayacağım.
Temel Süreç
1. İçerik Yönetimi ve İş Birliği için Bir Sprint Dalı Oluşturma
Bir geliştirme iterasyonu başladıktan sonra, operasyon meslektaşları Apidog'da bir iterasyon dalı oluşturarak, mevcut iterasyonda değişiklik içeren tüm belgeleri iş birliği için bu dalın içine yerleştirir ve ana dalı doğrudan etkilemekten kaçınır.
Oluşturulduktan sonra, ürün yöneticileri iterasyonda fiilen güncellenen özelliklere göre mevcut belgeleri bu iterasyon dalına aktarır ve yeni özellikler için doğrudan iterasyon dalında yeni belgeler oluşturur. Buradaki işlem, API dokümantasyonu için iterasyon dallarının kullanımıyla tamamen tutarlıdır.
Ana dalda koruma ayarladığımız için, ana daldaki belge içeriğinde doğrudan değişikliklere izin verilmez. Bu, kullanıcıların doğrudan görebileceği yayınlanmış dokümantasyondaki içeriği manuel olarak değiştiremeyeceğiniz anlamına gelir, bu da ürün dokümantasyonunu daha kararlı hale getirir ve rastgele değişikliklerin kullanıcılar tarafından yanlış içeriğin görülmesine yol açtığı durumları azaltır.
2. Her Belgeyi Yazmak için Güzel Markdown Düzenleyiciyi Kullanın
Ürün yöneticileri, mevcut iterasyonda güncellenmesi gereken dokümantasyonu iterasyon dalı içinde Markdown kullanarak yazacaktır. Apidog'un Markdown işlevselliği çok güçlüdür, düşük giriş engeliyle birçok karmaşık stili eklemek için tıklanabilen çeşitli görsel bileşenlere sahiptir, bu da ekstra çaba harcamadan kolayca güzel makaleler yazmanıza olanak tanır.
Genel MD stil görsel eklemesine ek olarak, Apidog aşağıdaki özel özellikleri eklemiştir:
- Belgelerin referans zincirleri oluşturarak birbirine bağlanmasını sağlayarak kesintisiz navigasyon sunan, okuyuculara daha sorunsuz bir deneyim sağlayan ve okuyucuların ihtiyaçlarını ve sorunlarını daha iyi çözen proje API'leri/belgelerini ekleyin - bu çok önemli bir özelliktir.
- Simgeler, vurgu blokları, tablolar, adımlar, Mermaid, videolar vb. gibi zengin kaynak ekleme işlevleri sağlayın, böylece belgelerin daha iyi görünmesi için kaynakları kendiniz bulmak veya MD stil sözdizimini öğrenmek için zaman harcamanıza gerek kalmaz.
3. Ürün/Operasyon Meslektaşları Belgeleri Parlatmak için İş Birliği Yapar
Ürün yöneticileri iterasyon dalında belgelerin ilk sürümünü yazdıktan sonra, belge kalitesini, netliğini ve kullanıcıya yardımcı olma düzeyini artırmak için belgeleri operasyon meslektaşlarına kullanıcı bakış açısından okumaları ve parlatma için değişiklik önerileri sunmaları için devreder.
Bu, eskiden en çok zaman alan ve zahmetli kısımdı, her iki taraf arasında karşılıklı iş birliği gerektiriyordu; bir taraf fikirlerini açıklıyor ve belirli kısımlar için somut değişiklik önerileri sunuyordu; sonra diğer taraf alıyor, anlıyor ve değişiklikleri fiilen yapıyordu. Bu ileri geri süreçte, yanlış anlaşılmalar, yanlış değişiklikler ve belge sürümleri arasında içerik farklılıkları gibi çeşitli sorunlar sıkça yaşanıyor, bu da verimliliği çok düşürüyordu.
Şimdi Apidog kullanarak, her iki taraf da belgelerde doğrudan değişiklik yapabilir, değişiklikler yapıldığında gerçek zamanlı mesaj bildirimleri IM'ye gönderilir, bu da diğerlerinin belgeye anında girmesine ve belirli değişiklikleri kolayca görmesine olanak tanır, bu da iş birliği verimliliğini büyük ölçüde artırır. İşte belirli adımlar:
- Ürün yöneticileri belgelerin ilk sürümünü oluşturur. Operasyon personeli bildirimi gördükten sonra belgeyi okur ve bu belgede değiştirmek istedikleri içeriği doğrudan düzenler.
- Değişiklikler kaydedildiğinde otomatik olarak bildirimleri tetikler, önceden yapılandırılmış IM grubuna değişiklik mesajı kartları gönderir. Grup üyeleri değişiklik özet mesaj kartlarını gördükten sonra, bildirim bağlantısına tıklayarak ilgili belgeye tek tıklamayla girebilirler.
- Değişiklik geçmişi aracılığıyla, mevcut sürüm ile orijinal sürümü seçerek farklılıkları karşılaştırabilir, diğer tarafın değişikliklerini kolayca görüntüleyebilir ve belgeyi nasıl ayarlayacağınıza karar verebilirsiniz. Önerileri kabul etmeyip orijinal sürüme geri dönebilir veya değişiklikleri kabul edip en son sürümü koruyabilirsiniz.
Ürün ve operasyon ekipleri, belge içeriği parlatılana ve herkesin onayladığı bir sürüm belirlenene kadar yukarıdaki adımları tekrarlar.
4. Resmi Belge Yayınlamadan Önce Hazırlık ve İnceleme
Belgelerdeki içerik ve ürün ekran görüntülerinin kullanıcıların erişebileceğiyle tamamen tutarlı olduğundan emin olmak için, ürünün üretim ortamında ekran görüntüleri almanız önerilir. Bu aynı zamanda üretim ortamında başlatılan yeni yeteneklerin düzgün çalıştığını doğrulamaya da olanak tanır. Operasyon personeli yeni özellikleri çevrimiçi kullandıktan ve ekran görüntüleri aldıktan sonra bunları makalelere ekler.
Operasyonlar, bu iterasyondan tamamlanmış içerik belgelerini onaylar, seçer ve ana dala birleştirme için bir MR isteği gönderir.
Operasyon yöneticisi veya diğer proje yöneticileri yayınlanacak belge içeriğini gözden geçirir, doğru olduğunu onaylar ve ardından ana dala birleştirmeyi seçer.
Birleştirme tamamlandıktan sonra, kullanıcılar yayınlanmış belgelere eriştiklerinde, ana dala birleştirilmiş en son içeriği görebilirler.
Diğer Avantajlar
Yukarıda tanıtılan yeteneklere ek olarak, Apidog, herkesin ihtiyaçlarını daha iyi karşılayan ürün dokümantasyon siteleri oluşturmasına yardımcı olmak için belgeleri yayınlama konusunda aşağıdaki özelliklere de sahiptir.
1. Ürün/Şirket Stiline Uygun Genel Dokümantasyon Sitesi Stillerini Ayarlayın
Yayınlanan dokümantasyon sitesinin genel stilini ayarlayarak, tüm web sitesinin stilini şirketinizin tonuyla daha uyumlu hale getirebilir ve kullanıcılara daha iyi bir deneyim sunmak için daha fazla ilgili kaynak ve şirket içerik bağlantısı ekleyebilirsiniz.
Apidog'un yardım dokümantasyonu kendi logosunu ve Apidog ile ilgili bazı kaynak bağlantılarını ayarlamıştır. Sol üstte şirket logosu, sağ üstte çeşitli şirketle ilgili kaynak bağlantıları bulunur ve geliştiricilerin daha çok önemsediği açık API dokümantasyonu da ürün dokümantasyonunun içine yerleştirilmiştir:
2. Sıfır Bakım Gerektiren Yayınlama Deneyimi
Apidog'da, yayınlama dokümantasyonu özelliğindeki "Yayınla" düğmesine tıklayarak tüm dokümantasyonu tek tıklamayla internete yayınlayabilir ve kullanıcılarınızın okumasını sağlayabilirsiniz. Apidog, herkesin kullanması için resmi olarak alan adları sağlar, bu da çok fazla bakım işinden tasarruf ettirir.
Elbette, dokümantasyonun kendi şirketinizin web sitesine daha çok benzemesini isterseniz, kendi şirketinizin alan adını kullanarak dokümantasyona erişmenizi sağlayan özel alan adı işlevselliği de sunuyoruz.
Ayrıca, yayınlanan ürün dokümantasyon sitelerinde düzenli arama, Algolia tam metin arama, GA entegrasyonu, yönlendirmeler ayarlama ve diğer gelişmiş yetenekleri basit işlemlerle kolayca ayarlayabilirsiniz. Bu yapılandırmalar, operatörlerin yeterli mühendislik yeteneğine sahip olmasını gerektirmez - arayüz rehberliğini ve yardım dokümantasyonunu takip ederek kolayca ayarlanabilirler.
3. Çoklu SEO Dostu Ayarlar
Apidog, yayınlanan dokümantasyon siteleri için temel ayarlara göre otomatik olarak makul Slug'lar oluşturarak kullanıcıların bunlara daha iyi erişmesini ve paylaşmasını sağlar.
Elbette, daha gelişmiş SEO ihtiyaçlarınız varsa, her bir belge için özel Slug, Meta Veri ve çeşitli diğer içerik ayarlarını da destekler.
Sonuç
Yukarıda, Apidog'un ürün dokümantasyonu bakımı için özel uygulaması yer almaktadır.
Yukarıda bahsedilen içeriğe ek olarak, ürün yardım dokümantasyonunu, geliştirici dokümantasyonunu ve API dokümantasyonunu tek bir stilde koruyabilir ve hepsini birbirine bağlayarak daha da iyi bir kullanıcı deneyimi sağlayabiliriz. Eğer mevcut durumunuz uygunsa, bu uygulamayı denemenizi ve diğer meslektaşlarınıza önermenizi rica ederiz. Umarım bu, ürün dokümantasyonu oluşturma çalışmalarınıza bir miktar verimlilik ve kalite iyileştirmesi getirebilir.