ما هي الأداة الجيدة لكتابة دليل المستخدم (ملف المساعدة)، الذي يتكامل مع التحكم في الإصدار [مغلق]
https://stackoverflow.com/questions/152241
-
02-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russianسؤال
الأشخاص الذين يكتبون دليل المستخدم ليسوا بالضرورة مبرمجين، ويحتاجون إلى محرر مرئي.إحدى القضايا الرئيسية هي الشكل الداخلي لأداة التأليف؛يجب أن يكون نصًا/html قابلاً للقراءة، لذلك من السهل مقارنة إصدارات الصفحات الفردية التي تم فحصها في التحكم في الإصدار.
المحلول
هناك منتجات احترافية أخرى تسمح بكتابة ملفات المساعدة ولديها دعم "معرف السياق" الذي يجعل المساعدة الحساسة للسياق ممكنة. وثيقة للمساعدة و مساعدة روبو هي هذا النوع من المنتجات.
نصائح أخرى
دوكبوك
(مصدر: docbook.org)
يمكن استخدام Microsoft HTML Help Workshop لإنشاء ملفات تعليمات CHM احترافية عالية الجودة.كل ما تحتاجه هو مجموعة من ملفات HTML.تقوم الأداة "بتجميع" كل هذه العناصر والحزم في ملف تعليمات واحد.يمكن إنشاء ملفات HTML باستخدام Microsoft Word/Frontpage أو حتى Dreamweaver.قد ترغب في التفكير في التحكم بالمصدر في ملفات HTML هذه.
في وظيفتي القديمة استخدموا أداة من برنامج madcap تسمى توهج.
ويبدو أن العمل بشكل جيد حقا.
التركيبة الجيدة التي يجب مراعاتها هي Subversion وDocBook وPublican.
في الوقت الحالي، تعد هذه إحدى سلاسل الأدوات المستخدمة من قبل أكبر مزود للحلول مفتوحة المصدر في العالم، والاسم وراء الكثير من الاستخدام العالمي لأنظمة التشغيل المستندة إلى Linux في سوق المؤسسات.يتم إنشاء معظم الوثائق الرسمية لـ Red Hat (والجميع تقريبًا) بهذه الطريقة.الشيء نفسه ينطبق على فيدورا.
"المؤيد" الرئيسي هنا هو أن هذه الأدوات متاحة مجانًا، مع تداخل قوي في سوق الكتاب التقنيين.كل ذلك سيكون قادرًا على الكتابة بلغة XML (لكن قد لا يرغب في ذلك)، ويعد التقاط DocBook بمثابة التقاط HTML في التسعينيات.Subversion هي أداة شائعة جدًا للتحكم في الإصدار، وهي مثل DocBook سهلة التنفيذ والاستخدام نسبيًا.تعد Publican أداة نشر رائعة يمكنها استخدام DocBook XML ونشرها بتنسيق PDF وHTML وHTML-single وما إلى ذلك.من الواضح أن كتابك يمكنهم استخدام WYSIWYG مثل Serna، لكنني أستخدم المقتطفات في Geany (على Fedora) أو TextMate (على OS X) شخصيًا.
"العيب" الرئيسي هو تصور التقنية.قد يرغب كتابك في استخدام WYSIWYG (ويمكنهم الحصول عليه)، ووفقًا لاحتياجاتك التوثيقية، قد يكون هذا هو ما ستستخدمه في النهاية.كما تعلم، هناك سوق لـ "الكتاب التقنيين" المتخصصين في إصلاح أنماط Microsoft Word (والترميز)، لذا فإن الحجج الداعية إلى فصل "التأليف" عن "النشر" تعتمد على حالات استخدام مثبتة ولكنها متميزة للمؤسسات التي تتطلب أن تكون الوثائق متوافقة مع نفس معايير الإنتاج الهندسي/البرمجة/المصدر.
بعض النصائح الشديدة التي سوف تحصل عليها تأتي من الأشخاص والشركات الذين تعرفوا على قيمة وثائق XML، وخاصة أولئك الذين يعملون في مجالات DITA، حيث تتمتع بعض الشركات متعددة الجنسيات بسمعة جيدة في عمليات الاستحواذ التي تتأثر بالتنسيق و توافر المعرفة بالمنتج.هناك أيضًا حجج مفادها أن قفل المستندات الخاصة بك بتنسيق "مثبت" أو مغلق لا يساعد في متطلبات الصيانة المستقبلية.هذا هو المكان الذي تحصل فيه الخيارات مفتوحة المصدر على الدعم على مستوى الشركة.بالإضافة إلى أنه من الواضح أنه مجاني.
يمكنك استخدام Subversion وMGTEK Help Producer.يقوم برنامج Help Producer بإنشاء ملفات تعليمات من مستندات Word.يأتي TortoiseSVN مع نصوص برمجية لمقارنة المراجعات المختلفة لمستندات Word، في Word نفسه (يحتوي Word على أداة لمقارنة الإصدارات).
سيحتاج المستخدمون لديك إلى أداة فرق مرئية تشبه تلك التي يقومون بتحريرها.إذا كانت غير تقنية إلى حد ما، فلن يعمل DocBook أو Latex (لقد حاولت منح المستخدمين كليهما، حتى أنني جربت Epic Editor كمحرر DocBook وهو مكلف للغاية ولكنه لم ينجح بشكل جيد بعد كل ذلك).إن التمسك بشيء يعرفونه (Word) سيمنعك من الكثير من الصداع.
لقد كنت مترددًا جدًا في اتباع هذا الطريق في البداية أيضًا، لأنني أردت حلاً أكثر "مثالية من الناحية الفنية"، لكنني أدركت مع مرور الوقت أن وجود مستخدمين سعداء ومنتجين هو الأكثر أهمية.فقط أقول إنني أعرف من أين أتيت، ولكن جرب مسار Word - فهو يعمل بشكل أفضل بكثير من الناحية العملية من جميع الحلول النصية "الخالصة" الموجودة هناك.لا يحب المستخدمون العاديون التحرير القائم على الترميز.
إذا كنت تستخدم Visual Studio، فألق نظرة على SandCastle - http://www.codeplex.com/Sandcastle.
هناك أيضًا بعض الأدوات التي تساعدك على إنشاء ملفات sandcastle، حاول البحث عن "sandcastle" على codeplex.واحد منهم هو SandCastle Help File Builder (http://www.codeplex.com/SHFB)، لكنني لم أستخدمه مطلقًا، لذا لا أعرف ما إذا كان المستخدمون غير التقنيين سيكونون سعداء بذلك.
Mapcap Flare هي أفضل أداة تجارية موجودة.كتبه المطورون السابقون لـRobodoc
لقد قمت بإنشاء نظام توثيق يسمى رجل إلى أسفل (Markdown/Html/Javascript/المستندات المرتبطة نسبيًا المستندة إلى الملفات لسهولة النقل) والتي من شأنها أن تخضع بسهولة للتحكم في الإصدار.جزء المحرر المرئي الذي يجب عليك اكتشافه بشكل منفصل - أستخدمه أحيانًا HTML-كيت والتي تحتوي على الأقل على ميزة المعاينة.
يرى ما هي أفضل طريقة لتخزين وثائق البرامج؟
إليك أداة أخرى للتحقق: شيليز
نحن نستخدم ملائم.إنه يتكامل بشكل جيد مع CI (قطعة أثرية للبناء القياسي) وهو أكثر حيوية من مستند Word على سبيل المثال.من الممكن أيضًا إنشاء ملفات PDF وتنسيقات أخرى عند الحاجة.
