وثائق معايير/هيكل/ستايل لخدمات الويب [مغلقة]

Question

يمكن لأي شخص أن يوصي مبادئ توجيهية رفيعة المستوى الوثائق على شبكة الإنترنت ؟

هذه هي الوثائق التي ينبغي أن تسمح لشخص ما مع عدم وجود المعرفة معين خدمة ويب أن يأتي بعيدا مع فهم أساسي من سبب وجوده ، خارطة الطريق أمثلة من الاستخدام.

هذه الوثائق يجب أن يصلح على اثنين المطبوعة الجانبين من الورق A4/Letter و تأخذ شخص أقل من 10 دقائق إلى قراءة.

لاحظ أن هذا هو التكميلية إلى API ذات المستوى المنخفض الوثائق المطور استخدام تستهلك واجهة.

Answer 1

أنا لست متأكدا من أنني قد التوجيهية ، ولكن أنا يمكن أن تظهر لك مثال على ما وجدته أن يكون مجموعة جيدة من مستندات ويب خدمات API.

http://www.flickr.com/services/api/

فليكر API الصفحات المبينة في شكل مقروء.هذه الصفحة في الأساس:

• وصلات إلى صفحات نظرة عامة
• Writeups من السيناريوهات الشائعة (تحميل الصور في هذا المثال)
• معلومات عن أدوات تستهلك API
• وصف مفصل من كل API طريقة تجميع حسب النشاط

وخاصة الصفحات التي تصف الوصول المشترك paterns (تحميل صورة, استبدال الصور), بالنسبة لي, حيوية.أنها تظهر المستهلك من API كيف نفعل الأشياء المشتركة و كيف تتوقع من الناس أن استخدام API الخاص بك.هذه النقطة الأخيرة مهمة - كنت أريد أن أقول "نحن نتوقع منك أن تتصل بنا مثل هذا باستخدام هذه الأساليب ، مع هذا النوع من معالجة الخطأ".عرض المستخدمين بعض أفضل الممارسات حول استخدام API و عليك حفظ نفسك حمولة كاملة من مكالمات الدعم.