WordPress Profesyonelleri için Ürün Belgeleri

Yayınlanan: 2017-07-28

Ürün belgeleri genellikle önemsiz olarak görülür, köşeleri kesebilirsiniz. Müşteriye değer sunabilecek veya gelir ve pazarlama gibi önemli iş alanlarını etkileyebilecek bir şey olarak görülmez. Bir WordPress uzmanı olarak Atlassian veya Cisco ile aynı şekilde belge yazmanız gerekmeyecek. Genellikle, insanlar "belgeleme" denilince akla, kimsenin okumadığı çok büyük bir rafta alfabetik olarak dizine alınmış kalın, basılı kullanım kılavuzlarının resimleri gelir.

Ama bu değişti:

Çevik ve DevOps'un ortaya çıkmasıyla birlikte, nakliye yazılımı daha hızlı hale geldi ve geliştirme döngüsü de daha dinamik hale geldi. Ve sonuç olarak, dokümantasyon artık sonsuza kadar kağıt üzerinde statik yazılı bir şey olmak yerine, en yeni sürümdeki mevcut durumu yansıtıyor. Belgeler, geliştirme döngüsüne entegre edilmiştir ve yazılım kadar sık güncellenir.

WordPress uzmanları neden ürün belgelerini önemsemeli?

Kullanışlı, güncel belgeler yalnızca kullanıcılarınızın hayatını kolaylaştırmakla kalmaz, aynı zamanda benzersiz bir pazarlama varlığı haline gelen bir cila düzeyi de ekler. Tersine, zayıf belgelerin olumsuz bir etkisi vardır. Muhtemelen bunu kendiniz deneyimlediniz: Çözümünü belgelerde bulmak için çok uğraştığınız bir sorunla karşılaştınız ve bulamadığınızda hayal kırıklığına uğradınız (ve muhtemelen sinirlendiniz). Ürün için para ödüyorsanız daha da kötüleşir.

Bir WordPress ajansında çalışıyorsanız, ilk tasarımdan varlıklara kadar bir projenin tüm alanlarında belgeler sunmak, aşağıdakileri gösteren bir profesyonellik düzeyi katacaktır:

Detaylara dikkat ediyorsun.
Müşterinizi ekstra mil kat edecek kadar önemsiyorsunuz.
Tasarım ve teknik proje kararlarınız konusunda şeffaf ve kendinize güveniyorsunuz.

MindTouch Pazarlama Başkan Yardımcısı Mike Puterbaugh, ürün belgelerinizin bir pazarlama varlığı olmasının 5 nedenini açıklayan bir Mashable makalesi yazdı. Şu sözlerle sözlerini tamamladı:

Bu seksi bir girişim değil, ancak size meslektaşlarınızın saygısını, daha etkili şirket yönetimini ve daha işbirlikçi bir ekip kazandıracak. Çünkü mesele bu çeyrekle veya bu yılla ilgili değil, daha çok rekabet avantajını ve uzun vadeli büyümeyi etkilemekle ilgili.

Yeterince motivasyon oluşturduğumuza göre, şunları yapacağız:

WordPress ile ilgili farklı ürün belgeleri türlerini keşfedin.
Her belge türünün ihtiyaçlarını tartışın ve uygulanabilir tavsiyeler sunun.
Ürün belgelerini nasıl planlayabileceğiniz ve üzerinde işbirliği yapabileceğiniz konusunda bazı başlangıç kılavuzları sunun. Özellikle bir WordPress ajansında çalışıyorsanız.

WordPress ürün belgelerinin türleri

Bir WordPress ürünü yalnızca eklentiler ve temalarla ilgili değildir. Bu bölümde ayrıca çevrimiçi yardım, REST API'leri ve mikro içerik adı verilen ilginç bir şeyi tartışacağız.

WordPress eklentileri

WordPress eklenti belgelerinin iki kalabalığa hitap etmesi gerekiyor: kullanıcılar ve geliştiriciler. Her birinin dokümantasyon ihtiyaçları, kullanılan yazı stili gibi farklıdır.

Kullanıcılar

Kullanıcıların dokümantasyon ihtiyaçları çoğunlukla sorun giderme ve yapılandırma etrafında döner. Buna, kullanıcıların denemesini sağlamak için eklentinizi çekici bir şekilde sunmanız gerektiğini ekleyin. WordPress eklenti pazarında her eklentinin kendi sayfası vardır. Aşağıdaki noktaları aklınızda bulundurun:

İndirmeyi ve kullanmayı teşvik eden ilgi çekici ve faydalı bir açıklama yazın.
Açıklamalarla birlikte Gösterge Tablosu eklenti yapılandırma sayfanızdan açıklamalı ekran görüntüleri ekleyin.
Sıkça sorulan sorular değil, yararlı olan soruları SSS'ye koyun.
Güncellenmiş ve iyi yazılmış bir Changelog'a sahip olun. Buraya şifreli veya özlü notlar eklemeyin.

Kullanıcılar belgeleri kullanırken muhtemelen bir çözüm bulmak için acele ve endişe içinde olduklarını unutmamalısınız. Açık, basit ve özlü yazın. Onlar için olduğundan daha zor hale getirme.

geliştiriciler

En iyi yazılım uygulamalarını ve resmi PHP kodlama standartlarını takip etmenin yanı sıra, dikkatinizi aşağıdaki alanlara odaklamalısınız:

eklenti kancaları

Bunlar, WordPress'in davranışını değiştirme işini yapar. Büyük olasılıkla WordPress eklentiniz bunları kullanıyor. Eklenti kancaları kodun önemli bir parçası olduğundan, bunları nasıl kullandığınızı ve hangi WordPress işlevlerinde yer aldıklarını belgelemelisiniz.

şablon etiketleri

Şablon etiketleri, bir WordPress Eklentisinin işlevselliği geliştirmesinin başka bir yoludur. Yazdığınız şablon etiketi işlevlerini belgeleyin. Diğer kullanıcıların veya geliştiricilerin WordPress sitelerindeki etiketleri nasıl kullanabileceğine dair örnekler ekleyin.

seçenekler

Seçenekler, belirli bilgi parçalarını bir WordPress veritabanında saklamanın bir yoludur. Bu, add_option ve get_options işlevleri aracılığıyla yapılır. Bu durumda, bu işlevlere ilettiğiniz parametreleri belgeleyin.

veri tabanı

Eklentiler sıklıkla bir veritabanından birçok farklı şey okur ve yazar. Bunlar temel işlemler olduğundan, bunları belgelemek, diğer geliştiricilerin eklentinizin nasıl çalıştığını anlamalarına büyük ölçüde yardımcı olacaktır.

WordPress Temaları

Temalar için dokümantasyon oluşturabileceğiniz iki farklı alan bulunmaktadır. Birincisi kaynak dosyalar. Yorumlu CSS dosyalarının anlaşılması ve okunması, olmayanlardan daha kolaydır. Size yardımcı olması için css_doc gibi bir araç kullanın. Bu, bir JavaDoc stili belge oluşturur ve yayınlanabilir:

Diğer alan Stil kılavuzlarıdır. Bu belgeler, öğelerin nasıl görünmesi gerektiğini ve hangi durumlarda kullanılması gerektiğini açıklar. Tutarlılığı zorlarlar ve işbirliğini de kolaylaştırırlar. Çok sayıda harika örnek içerdiği için Hubspot'un 20 çarpıcı marka stil kılavuzu örneği makalesini okuyabilirsiniz.

Yine, resmi WordPress CSS kodlama standartlarına başvurmayı unutmayın.

Tasarım öğelerini bu kadar ayrıntılı bir şekilde belgelemek, bir WordPress ajansıysanız yeni çalışanların işe alınmasına da yardımcı olur. Stil kılavuzları, yeni ve geçmiş müşteri çalışmaları için öğreticiler veya referans materyalleri olarak kullanılabilir.

Çevrimiçi yardım

Çevrimiçi yardım belirli bir kullanıcı sorununu çözmeyi amaçladığından, genel görevler ve sorunların bir listesiyle başlamak doğru yoldur. Liste ilk başta ayrıntılı olmasa da, mümkün olduğunca çok sayıda somut ürün üretmek için zaman ayırın. Buradaki fikir, bu görev ve sorunların her biri için bir çevrimiçi yardım dosyası yazmak ve bunları ilgili bilgilere köprülemek. Bir kullanıcının uygulamanız içinde izleyebileceği ve yapabileceği farklı yolları belirlemek için kullanıcı yolculukları oluşturabilirsiniz. Sık sorulan soruları ve sorunlu alanları fark etmek için destek e-postalarına dalmak, bilgi tabanınızı güncel ve kullanışlı tutmanın iyi bir yoludur.

Spring into Technical Writing'in yazarı Barry J. Rosenberg, iyi yardım dosyaları yazmak için aşağıdaki tavsiyeleri sunuyor:

Her yardım dosyasını mümkün olduğunca kısa tutun. Numaralandırılmış listeleri madde işaretli listelere tercih edin. Konuyu dağıtmayın, dipnot vermeyin ve istemeyin. Her yardım dosyasını tek bir ayrı göreve odaklayın.

mikro içerik

Mikro içeriğin iki tanımı vardır: ilki, belirli bir makalenin özünü elde etmek için kullanıcıların gözden geçirdiği başlıklar ve bölümler gibi içeriktir. İkincisi, kendi başına durabilen ve kullanıcı deneyimini geliştirmek için kullanılan küçük içerik parçalarıdır. Aklımızda olan mükemmel bir örnek, Slack'in “birkaç kişi yazıyor..” bitidir. (Slack mükemmel yazılmış mikro içerikle dolu olsa da).

Bu bit, aynı kanalda aynı anda 3'ten fazla kişi yazdığında tetiklenir. Slack, şu anda yazan kişilerin bir listesini yazdırmak yerine, bu sıkıcı bilgiyi alır ve ona biraz eğlence katar. Tartışma gerçekten kızışmaya başlıyor ve bunu gösteriyor. Bu, ürün belgelerinin (uygulama mesajları bunun bir parçasıdır, değil mi?) insanları sizin hakkınızda nasıl konuşturduğunun (ve yukarıdaki gibi komik memler yarattığının) mükemmel bir örneğidir.

REST API'si

REST API'lerini belgelemek başlı başına ayrı bir sanattır. Tüm teknik yazılarda olduğu gibi, tanımlarda da kısalık, netlik ve basitliği hedeflemelisiniz. REST API'lerinin kendi biçimleri ve incelikleri olduğundan, Tom Johnson'ın I'd Before Be Writing blogunda API'leri belgelemek için mükemmel kılavuzunu incelemekten daha kötü bir şey yapamazsınız.

İşbirliği ve planlama belgeleri

Sonuç olarak, dokümantasyon ürün tasarımının bir parçası olmalıdır. Bu nedenle, yazılım döngünüzde fazladan bir boru hattına sahip olarak yaklaşmalısınız. Bu, en güncel dokümantasyon sürümünü depolamak için yazılım havuzlarını kullanmak, görevleri ve sorunları izlemek için hata/sorun izleyicileri kullanmak, dokümantasyon proje planlamasını yol haritanıza dahil etmek ve son fakat en az değil, diğer insanlarla işbirliği yapmak anlamına gelir. Nasıl başlayacağınıza dair kaba bir taslak aşağıdaki gibi olabilir:

Kullanıcının bilmek isteyeceği her şeyi ve ayrıca metin yazmanız gereken alanları kaydedin.
Her şeye sahip olduğunuzda, bunları kategoriler halinde gruplandırın ve belge başlıkları oluşturun.
Her belge için başlık, açıklama, hedef kitle, medya (belgenin hangi formu olacak), uzunluk, ne kadar zaman alacağı vb. ayrıntıları içeren bir özellik yazın.
Proje planlamanıza dokümantasyon özelliklerinden tahminleri ekleyin.

Ürün dokümantasyonu tüm alanları kapsadığından, organizasyon içinde farklı kişilerle çalışmanız gerekeceği neredeyse kesindir. Oturup tüm bunların nasıl gideceğine dair bir tür süreç üzerinde anlaşmak iyi bir fikirdir. Her projede olduğu gibi, teknik yardım sağlayacak paydaşların yanı sıra değişiklikleri gözden geçirecek ve düzenleyecek paydaşları da belirlemelisiniz.

Sürecin farklı aşamaları olmalıdır. Bunlar, bilginin nerede toplandığını, belgenin ne zaman yazıldığını, edebi redaksiyon için ne zaman hazır olduğunu, teknik yorumlar, yayıncılık vb. Edebi, teknik ve içerikle ilgili yorumlar arasındaki farkı vurgulayın. Örneğin, bir ekip liderinden belgeniz hakkında yorum yapmasını istediğinizde bu pek kullanışlı değildir ve teknik olarak ilgili bilgiler yerine dilbilgisi ve noktalama işaretleri için ağlarsınız.

Kapanış

Ürün belgeleri, uzun vadede karşılığını veren bir varlıktır. Müşterinize değer verir. Hatta o kadar iyi olabilir ki, örneğin Stripe'in API belgeleri gibi, insanlar forumlarda bu konuda çıldırır. Bu, etkileşimi artırır ve markanızı ve ürününüzü doğal ve güçlü bir şekilde tanıtır. Yaratıcı mikro içerikle birleştiğinde, Mike Puterbaugh'un ürün belgelerinin “pazarlamanın gizli silahı” olduğunu söylediğinde ne demek istediğini elde ediyor.