باستخدام MAML للتوثيق المفاهيمي للمكتبة [مغلقة

Question

أنا أعمل على مكتبة جديدة وأستخدم تعليقات XML لتوثيق API جنبًا إلى جنب مع Sandcastle التي تعمل بشكل جيد.

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

لدي خياران:

1. استخدم بعض محرك wiki وكتابة نمط الوثائق.
2. استخدم MAML الذي يبدو لهذا الغرض.

يبدو استخدام Wiki حلًا آمنًا لأن هناك العديد من المحركات المستقرة والشعبية والمجانية المتاحة ولكن API والوثائق المفاهيمية لن تسير جنبًا إلى جنب (الارتباط المتقاطع ، المظهر وما إلى ذلك). يعني استخدام MAML منحنى التعلم ولست متأكدًا من مدى نضوجته وما هي مزاياه/عيوبه.

هل استخدمت MAML/WIKI لهذا الغرض وماذا كان تعلمك؟ ماذا تقترح لي؟

Answer 1

أنا شخصياً أحب حرية العمل مع ويكي. في هذه المرحلة ، لديك بعض الخيارات اللائقة لتحرير MAML

• Docproject
• Sandcastle Help File Builder

لا أستطيع التحدث كثيرًا إلى Docproject (على الرغم من أنه يبدو لطيفًا). في الوقت الحالي ، أستخدم SHFB لدمج وثائق API وبعض المستندات المفاهيمية في MAML. المحرر لائق وأكثر من كافٍ لاحتياجاتي. يمكنني بسهولة إعداد جدول المحتويات والارتباط بين واجهة برمجة التطبيقات والوثائق المفاهيمية. مورد جيد للنظر في الأمثلة Sandcastlestyles.

كما هو الحال مع كل الأشياء ، هناك بعض الأسئلة المهمة التي يجب طرحها.

• هل لديك أي متطلبات لشحن الوثائق الخاصة بك في حزمة واحدة؟ في حالتي ، كنت بحاجة إلى شحن كل شيء في حزمة واحدة مجمعة لطيفة. لا يمكنك فعل ذلك مع ويكي ، ولكن يمكنك القيام بذلك مع Sandcastle.
• هل ستكون الشخص الوحيد الذي يقوم بتحديث المحتوى المفاهيمي؟ معظم الويكي لديها محرر لطيف حقًا وقدرة على الارتباط بسرعة بين الموضوعات. الأداة الوحيدة التي تحتاجها لتحرير المحتوى هي متصفح ، والذي قد يكون مطلبًا لكاتب أقل ذكاءً تقنيًا.