Hata mesajına ilgili belgelere bir bağlantı eklensin mi?

Harici geliştiriciler tarafından kullanılan ticari bir kütüphane ve kod örnekleri oluşturuyoruz. Kütüphanenin nasıl kullanılacağını kapsamlı bir şekilde açıklayan (kapalı, kayıtlı kullanıcılar tarafından kullanılabilir) belgelere sahibiz.

Geliştiricilerin çoğu ilk kez kullanıldığından, birçok temel hata ile karşılaşılır.

Hata günlüğüne belgelere bağlantılar eklemek uygun mu? Olası olumsuz yanları nelerdir? Birkaçını öngörebilirim, ancak aşağıdakilerin üstesinden gelmek mümkün görünüyor

• Dokümantasyon URL'si eski
• En son belgelere yansıtılmayan sürüme özgü hatalar
• Başka bir şey yanlış ve geliştiricinin zamanını alakasız bir belgeye göndererek harcıyoruz

Ne demek istediğimin bir örneğinin altında, kalın metin eklemek iyi bir fikir mi?

[HATA] org.apache.maven.plugins hedefi yürütülemedi: maven-archetype-plugin: 1.2.3: proje tek başına pom'da oluştur (varsayılan-cli): İstenen arketip mevcut değil (com.example.library. arketipler: kütüphane-arketip-boş: 1.2.3.0) -> Daha fazla bilgi ve olası sorun giderme için lütfen http://example.com/docs/setting-up-an-archetype adresine bakın.

Göre bu hata mesajı kurallar ve deneyimlerime, insanlar belgelerine ya da okuma değil zaman kazanmak ister. Bir hatayı Google'a eklemek de onların ötesinde olabilir, bu yüzden tıklamak için bir nedenleri olduğunda bir bağlantı ekleyin.

Son olarak, muhtemelen Nielsen'in İlk Bilgisayar Dokümantasyonu Yasasını biliyorsunuzdur: insanlar okumuyor. Bu bulgu, kullanıcıların görevleri için gerekli olmayan herhangi bir okumadan gerçekten uzak durdukları web siteleri için daha da güçlüdür. Yardım? Asla.

Kullanıcılar sistem belgelerini yalnızca sorun yaşadıklarında okurlar (bu İkinci Yasadır). Bir hatadan kurtulmak istediklerinde özellikle dikkatli olurlar. Bu göz önüne alındığında, kullanıcılara az miktarda bilgi vermek için hata mesajlarını bir eğitim kaynağı olarak kullanabilirsiniz. Elbette, hata mesajları tüm Web içeriğinde olduğu gibi kısa ve öz olmalıdır. Bununla birlikte, hata mesajları yine de kullanıcılara sistemin nasıl çalıştığı hakkında biraz bilgi verebilir ve onlara daha iyi kullanmaları için gereken bilgileri verebilir. Bu amaçla, Web'in altında yatan teknoloji başka bir yönergeyi mümkün kılar:

Köprü metni bağlantıları, ek arka plan malzemesi veya sorunun açıklamasıyla birlikte bir sayfaya kısa bir hata iletisi bağlamak için kullanılabilir. (Yine de aşırıya kaçmayın.)

Evet en doğrusu AMA:

• Bağlantı çürümesi bir sorun olacak, İdeal olarak bağlantıyı bilinen bir hedef belgeden dinamik olarak oluşturun, ancak öneki bir yapılandırma biçiminden alın. Sunucu değişirse, bu yapılandırma öğesini güncelleyerek eski kodu geçerli tutabilirsiniz. Ayrıca, yalnızca bu önek yapılandırmasını değiştirerek dokümanı yerel olarak da kullanabilirsiniz.
• Sürüm oluşturma : Aynı ruh halinde, bağlantıyı sürümde bazı kapasitelere dahil edebiliyorsanız bağlantı her zaman belgelerin doğru sürümüne işaret eder.
• Belgeyi düzenlenebilir hale getirin Belgeleriniz için hataları dinamik olarak düzeltebileceğiniz wiki türü bir site gibi bir şey, ideal olarak kullanıcıların doğrudan sayfaya yorum yapmalarına da izin verir. bu, kullanıcılarınızın katılmasını ve ihtiyaç duyduklarını bulmasını çok daha kolay hale getirecek ve dokümanınızı iyi çalışır durumda tutmak için altın bilgi alacaksınız, ancak düzenli olarak izlediğinizden ve en önemlisi kendiniz aktif olarak katıldığınızdan emin olun .
• Oluşturulan şablonlar , derleme sisteminizin doğrudan koddaki ek açıklamalardan belgeler için temel şablonu oluşturmasını sağlar. Yine de basit tutun, ancak bu her bağlantının her zaman geçerli bir belgeye işaret etmesini sağlayacaktır. Bir wiki kullanıyorsanız, bu şablonları kolayca zorlayabildiğinizden emin olun ve dokümantasyon sitesini kodunuz için yaptığınız şekilde tanıtabildiğinizden emin olun (prod sitesinden farklı bir geliştirme sitesine sahip olun ve prod i prod sitesindeki ekleri otomatik olarak gerçekleştirin).

Java veya .NET ile geliştirirseniz, belge bir jar dosyasına veya DLL dosyasına dahil edilebilir ve öneki değiştirerek kodunuz yerel olarak getirilebilir.

Wiki yaklaşımını seçerseniz, DokuWiki'yi basitliği ve yapı sisteminden otomatik enjeksiyon için çok kolay hale getirecek düz metin dosyalarına dayanması için sıcak bir şekilde öneririm . Bununla birlikte, ortamınızın veya müşterilerinizin bunun iyi bir YMMV olup olmayacağını gerçekten bilmesi için yeterli bilmiyorum.

Oluşturduğum en başarılı araçlardan bazıları, hata mesajının görevi gerçekleştirecek gerçek kullanıcıyı hedeflediği benzer bir yaklaşımı aldı. Bu, hatanın uygun soyutlama düzeyinde olduğundan emin olmak için çok sayıda yakalama ve sarma yapmam gerektiği anlamına geliyordu. Ayrıca, her hata mesajının en olası hata kaynaklarını içerdiğinden ve potansiyel çözümlere işaret ettiğinden emin oldum. "Xxxx yapılandırma değerini ayarlamayı unuttunuz mu?" Burada XXX ve hata, hatanın oluştuğu bağlamdan üretilir.

Bu yaklaşım biraz daha basit ama aynı zamanda daha sınırlıydı. Bununla birlikte, gerektiğinde bağlantı çürümesi mümkün olmadığında belgelerin her zaman mevcut olacağı yukarı tarafa sahiptir.

Yaklaşımınız bir sonraki evrim. Çok daha karmaşık ama aynı zamanda çok daha fazla potansiyel getirisi var. Gerçi pahalı olacak ama doğru yapılırsa kolayca kendisi için ödeyecek.

Çevrimiçi değil, kitaplıkla birlikte verilen çevrimdışı belgelere işaret etmeyi tercih etmelisiniz.

(com.example.library.archetypes: kütüphane-arketip-boş: 1.2.3.0) -> Daha fazla bilgi ve olası sorun giderme için lütfen /usr/share/myprog-3.8.1/docs/setting-up-an-archetype adresine bakın.

(açıkçası bir Windows kütüphanesi olsaydı, yol farklı olurdu).

Buradaki faydalar:

• Bu şekilde dokümantasyon her zaman kütüphane ile senkronize olur. İnsanlar eski kütüphane sürümleriyle geliştirir ve sorunları giderir. Ve şirketiniz adını değiştirebilir, ürünün adını değiştirebilir ya da birileri yenilemek için topu bırakabilir example.com.

• Web hızla değişiyor. Verdiğiniz bağlantı http, ancak birkaç yıl içinde büyük tarayıcıları sadece destekleyecektir https. Ya da hepimiz gopherprotokole geri dönebiliriz .

• Uygulama sorunlarını giderme, her zaman internet erişimi olan (veya en azından alan adınıza doğrudan erişim) bir ortamda gerçekleşmez.

• Belgelerinizin bir "kimlik doğrulama" duvarının arkasında olduğunu belirtiyorsunuz. Sadece bir hata mesajını anlamak için bir web sitesinde bir hesap oluşturmak zorunda değilsiniz (bu yüzden SO insanların giriş yapmasını gerektirmez).

Bu probleme yaklaşmanın gerçekten başarılı bir yolu var. İletiyle birleştirilmiş istisnanın, bunları bir web aramasına yapıştırmanın tam olarak bu sorunla ilgili tüm yayınları kolayca bulabileceği kadar benzersiz olduğundan emin olun.

Boş gösterici istisnalarından bu kadar nefret etmemin gizli nedeni budur. Elbette null'u kontrol etmemiz gerektiğinden nefret ediyorum ama beni en çok rahatsız eden şey, bir tanesiyle karşılaştığımda, aramam gereken tek benzersiz tanımlayıcının geçici bir satır numarası olmasıdır.

Evet, bunları arayabilmek istiyorum. Tabii, bunun olduğunu biliyorum çünkü bir şey boş bırakıldı ve sonra kullanıldı. Her zaman hemen belli olmayan şey, NEDEN bir şey boş bırakıldı.

Bu yüzden, diğer tüm dokümantasyon çözümlerini göz önünde bulundurun. Ama yapabileceğin en tembel şey, bana en iyisini yapacak, bana google yapabileceğim bir şey vermektir.

Lütfen?