على الرغم من أن الاجتماع الثاني لكتابة مستندات موسكو عقد قبل شهر ، إلا أنه لم يفت الأوان أبدًا لنشر تقرير وملخصات قصيرة للتقارير. تمكنا من مناقشة كل شيء عمليًا تقريبًا: من توثيق واجهة برمجة تطبيقات RESTful إلى المسارات المهنية للكاتب الفني.
بالمناسبة ، لم تجمع Mitap "الحي اليهودي الفني" فحسب ، بل جمعت أيضًا مجموعة واسعة من المتخصصين الآخرين الذين يعملون بطريقة أو بأخرى مع توثيق المشروع: قادة الفرق والمحللين والمختبرين وحتى مدير فني واحد.
عقد اجتماعنا في 14 أكتوبر ، الأحد (دخل إلى أعلى الأسئلة الأكثر شيوعًا عنه ، "لماذا يوم الأحد؟") في مكتب IPONWEB. تقام مسيرات "كتابة المستندات" في جميع أنحاء العالم من بنغالور إلى سان فرانسيسكو ، من لندن إلى سيول ، الفرع الروسي من المجتمع يكتسب نشاطًا فقط ، ولكن هناك بالفعل فروع في موسكو وسان بطرسبرغ ونوفوسيبيرسك.
انطون تلين ، لماذا وكيف نقوم بتعليمات الفيديوفيديوشرائحيدير أنطون قسم التوثيق الفني في VLSI ، والذي يصنع نظامًا إلكترونيًا لإدارة المستندات. لماذا فيديو؟ الناس لا يريدون قراءة التعليمات ، يريدون حل مشكلة. يريد الناس أن يتم شرحهم بوضوح ووضوح.
يعد الفيديو طريقة ملائمة لتقديم كمية كبيرة من المعلومات ، وتنفيذ برنامج نصي في ديناميكيات ، وسلسلة من الإجراءات. يمكنك أيضًا إبراز انتباه المستخدم بالموسيقى أو الدبلجة.
إذا كان المنتج معقدًا ولا يحتوي على واجهة مدروسة جيدًا ، فمن الصعب نقل جوهره إلى المستخدم بدون الجزء المرئي. زائد هو أنه يقلل من تكلفة الدعم الفني.
سلبيات - غير مناسبة لجميع تنسيقات النشر ، فمن الصعب تضمينها في doc و pdf. من الصعب البحث عنها. مقاطع الفيديو عالية الجودة أكثر تكلفة.
مشكلة أخرى ملحة هي تعقيد التحديث ، لكن حملة أنطون حلت هذه المشكلة. رفضوا تسجيل لقطات شاشة (لقطات الشاشة) لصالح لقطات شاشة عالية الجودة.
تستخدم الشركة صيغتي فيديو:
1. تعليمات الفيديو هي سلسلة من الإجراءات ، بالتفصيل والخطوات. المدة ~ 2 دقيقة. 1 تعليمات مشكلة واحدة. لا يتحدث عن جميع النوافذ ، الغربان ، الأزرار. ثم أضافت الدبلجة ، وموسيقى الخلفية ، وتفسيرات النص ، والتسميات التوضيحية.
2. فيديو توضيحي. هذا شيء عند تقاطع تعليمات المنتج والعرض التقديمي. يحل العرض العام بدون تفاصيل فنية العديد من المشكلات أو السيناريوهات. قد يتضمن هذا الفيديو الأشخاص والرسوم المتحركة. مدة 2-3 دقائق.
الأدوات: Adobe Premiere و Adobe After Effect للتحرير ، Adobe Audition للصوت ، Photoshop و Snagit لتحرير الصور. تم تجميع المشروع من مجموعة متنوعة من لقطات الشاشة ، والتي ليست ذات صلة أو خاطئة ثم من السهل استبدالها. بعد ذلك ، رسم حركة الماوس والرسوم المتحركة والصوت.
قرروا استخدام مذيعين غير محترفين للدبلجة ، لأنهم بدوا رسميين للغاية ، لذلك يستخدمون صوت موظف الشركة ، إيليا ، الذي يغني في مجموعة النوتات المعدنية. بعد مجموعة من المعلومات ، يتم بالضرورة التوقف لمدة ثانيتين للفهم.
يتم نشر مقاطع الفيديو على الاستضافة الخاصة بك وعلى Youtube. الجانب السلبي يمنعه من قبل العديد من الشركات لأسباب أمنية.
بالطبع ، تجمع VLSI جميع الإحصائيات المتاحة: متوسط وقت المشاهدة ، الإعجابات ، مكالمات الدعم الفني التي تم إغلاقها باستخدام رابط الفيديو.
نيكولاي فولينكين ، كاتب تقني ، الإصدار 2.0.1فيديوشرائحهذا تكرار ، أو بشكل أفضل ، إضافة إلى التقرير من مؤتمر SECR. شاهد نيكولاي الكتاب التقنيين لفترة طويلة ولاحظ أنهم لا يعرفون دائمًا كيفية تبرير وقياس فوائدهم ، والقادة الذين حددوا لهم المهام أيضًا.
هناك بعض المهام ذات الصلة التي يمكن للكتاب التقنيين حلها. قال نيكولاي ما المسارات المهنية ومجموعات المهارات التي تحتوي على أوصاف فنية ، وكيفية بيع مهامك الجديدة إلى الشركة.
5 أدوار يمكن أن يلعبها كاتب تقني:
1.
docops - devops للتوثيق ، كاتب / مبرمج ، يمكنه أتمتة إنشاء والتحقق وتحميل الوثائق وتدريب الفريق للعمل معها وإعادة بناء جميع العمليات من حوله.
يتم تقليل الفوائد من العمل اليدوي وتوفير الموارد وسرعات تسليم الميزات أعلى.
2.
كاتب UX - متخصص في كتابة النصوص في الواجهات.
الفوائد - لا يفهم المصممون أو القصائد أو المحللون أو مطورو الواجهة الأمامية دائمًا كيفية الكتابة بشكل صحيح وكيفية نقل الوظائف والأزرار والتحولات إلى المستخدم. تتم كتابة النصوص وفقًا لمبدأ من قام أولًا ونعال. راحة الواجهة ، مما يقلل من وقت الدعم الفني.
3. يتحدث
المبشر التقني عن التكنولوجيا ، ويتفاعل مع المجتمع ، ويشكلها.
الفوائد - زيادة الثقة والولاء للشركة ، للمنتج ، وتبسيط التوظيف ، والعلامة التجارية للموارد البشرية.
4.
مدير المعرفة - يستكشف كيف تنتج الشركة وتخزنها وتنقل المعرفة. يؤسس هذه العمليات بحيث لا تتسرب المعرفة.
الفوائد - تقليل عامل الباص ، وسرعة تكيف الموظفين ، سواء للمبتدئين أو أثناء الانتقال ، وإعادة استخدام المعرفة ، والحد من المخاطر.
5.
مالك التوثيق - رئيس الوزراء ومحلل التوثيق. يقوم ببناء نظام الاتصال وتفاعل المستخدم بأكمله في الوثائق.
الفائدة مرة أخرى في خفض تكاليف الدعم.
خلال المناقشة ، ذكرنا هذا الدور المتكامل كمدير محتوى ، والذي لم يتم ذكره في التقرير.
كونستانتين فالييف ، فوليانتفيديوشرائحتحدث قسطنطين من Restrim عن أداة
Foliant - تنفيذ سير عمل docops استنادًا إلى لغة Markdown. قبل عام ، كجزء من
ميني هايبرباتون في ياندكس ، تحدث كونستانتين بالفعل عن فوليانت ، وقد تغير الكثير منذ ذلك الحين.
تتم كتابة الوثائق في ملفات MD ، وتكمن في أماكن مختلفة ، وتدعم الأداة التكامل المستمر والتجميع التلقائي ، كما تتيح لك توسيع MD حسب رغبتك.
المتطلبات: تحتاج إلى إعطاء docx للعملاء و PDF مع طباعة جيدة ، ولديهم مصادر يمكن قراءتها بواسطة الإنسان (وليس XML).
تحت غطاء المحرك ، يتم استخدام محول Pandoc عالمي ، Python ، يتم كتابة نصوص bash في الأعلى. ولكن مع مرور الوقت ، زاد عدد النصوص البرمجية ، لذلك تم إعادة كتابتها في تطبيق واحد متآلف.
من المونوليث ، قاموا بعد ذلك بعمل هيكل معياري مع النواة التي تتحكم في التجميع ، والمعالجات الأولية التي تحول MD لعمل المجمعين ، والمجمعين أنفسهم.
Foliant هو في الأساس الغراء بين الأدوات الجيدة (mkdoc ، pandoc ، slate ، اللاتكس). يحاولون الآن تعليم كيفية استهلاك مصادر التوثيق من تنسيقات مختلفة.
يوجد في مجلد المشروع تكوين لهيكل الوثيقة النهائية والأنماط وملفات MD الفعلية ، ثم يأخذ المعالجون المسبقون ملفات MD المصدر ويطبقون المعالجة عليهم لجعل MD المطلوب بأسلوب all.md (md بأسلوب أوراق الشجر) ، ثم جامعي المستندات النهائية ( pandoc، mkdoc) تجعلها أهدافًا (وثائق). بعد تجميع MD ، يتم تشغيل linters للتحقق من بناء الجملة. يتم أيضًا إرسال إشعارات الإنشاء حول الإصدارات أو الأخطاء.
يمكن جمع كل هذا في Docker ، بحيث يتم تسليم جميع الحزم بطريقة واحدة ، وليس كل على حدة.
يدعم Foliant المتقدم ، ويمكن استخراج أجزاء من التعليمات البرمجية من Gitlab / Github والصور ذات التخطيطات من Simpli ، ويمكن رسم مخططات ، واستبدال المعلمات في النص ، وعبارات شرطية.
نيكيتا Samokhvalov ، وثائق شاملة على RESTful APIفيديوشرائحأخبر نيكيتا ساموخفالوف ، المدير الفني لـ Notamed ، كيف قاموا بتكوين جيل من وثائق API استنادًا إلى Open API 3.0.
مثل أي شخص آخر ، بدأوا باستخدام محرّر مستندات Google ، ولكن ليس لديه إصدار ولا القدرة على إنشاء فروع. ثم بدأوا للتو في كتابة ملفات MD في المستودع ، وتم حل مشكلة الإصدار وإنشاء الفروع ، ولكن كل شيء كان بطيئًا. ثم جاء إلى الجيل التلقائي.
كان للوثائق المتطلبات التالية: الوراثة وإعادة استخدام أجزاء من الوثائق ، والقدرة على توفير رابط لأوصاف المعلمات والأساليب ، ومعلومات عن التمايز بين حقوق الوصول ، والتوثيق ككود (عمليات النشر والتغييرات المتزامنة). بالإضافة إلى ذلك ، لا يتم نشر الوثائق علنًا ، فقط لفريقك وفرق تطوير الخريجين.
لقد اخترنا مواصفات OpenAPI 3.0. لماذا؟ إنه الأحدث ، ويدعم المزيد من الميزات ، على الرغم من أنه لا يزال هناك نظام بيئي صغير وخبرة حوله.
أخذوا أداة
السيقان (يعرض ملفات MD في صفحة هبوط جميلة مع أمثلة للاستعلامات ووصف الأساليب والمعلمات)
و Widdershins (yaml / json to MD Converter) ، كما كتبوا حزمة خاصة بهم (يثبت كل التبعيات اللازمة ، ويعمل من خلال npm ، ويتحقق أيضًا صحة هيكل تخصيص الملفات).
يتم إعداد البيئة وتجميع الوثائق على سطر واحد في وحدة التحكم. تقع الملفات التي تحتاج إلى إعادة استخدامها في كل مشروع ، على سبيل المثال ، وصف التفويض ، في التبعيات / المجلد.
تحدثت نيكيتا أيضًا عن كيفية عملها مع الفروع في فريق موزع ، عندما تكون المهمة هي تحديث الوثائق ، وبالطبع ، حول المآزق والصعوبات التي رافقت تنفيذ OpenAPI 3.0.
سفيتلانا نوفيكوفا ، إدارة المعرفة باستخدام مصفوفة الكفاءةفيديوشرائحسفيتلانا (بالمناسبة ، هذا أنا) تحدث عن كيف قاموا في الشركة بترتيب إعادة تشغيل الأداة من نهاية إلى نهاية من مجال إدارة شؤون الموظفين كمصفوفة كفاءة ، ما هو استخدام إدارة المعرفة بهذه الطريقة ، كيف تساعد الأداة على تقليل عامل الحافلة ، من الأفضل ركوب الوافدين الجدد ، حتى العثور على أجزاء كود إعادة البيع.
دانيلا ميدفيديف ، NeuroCodeفيديوتحدثت Danila عن أداة مفهومة للجميع ، وربما قبل عصرنا ، لنمذجة وتخزين المعرفة تسمى NeuroCode.
هذه الأداة مفيدة لأي شخص يشارك في تصميم أنظمة تكنولوجيا المعلومات. على وجه الخصوص ، تقترح Danila التخلي عن الأنظمة المستندة إلى المستندات. يعتبر أي نظام بمثابة شبكة ، وفقًا للعقد التي يتم نقل بعض المعلومات عنها. تخضع جميع عناصر النظام لهذا المبدأ - تحديثات الدفع ونقل المستندات ونقل الملاحظات. الغرض من NeuroCode هو "تقليل التكاليف غير المنتجة لدعم العمليات وتعزيز الذكاء الجماعي للمنظمة".
نما مشروع NeuroCode من حل المشكلة - كيفية إنشاء مستودع جيد للمعلومات لفريق أو لنفسك ، وكيفية إنشاء نموذج للمعلومات. النموذج الأولي للنظام مصنوع ويعمل الآن ، يتم اختباره الآن بمساعدة مهندسي النظام ومهندسي الأعمال. يحتوي النظام على واجهة قابلة للتحجيم ويستند إلى بنية بيانات كسورية. كما أنه يعتمد على أفكار دوجلاس إنجلبارت (هذا هو أحد الباحثين الأوائل في واجهة الإنسان والآلة ، ومؤلف مفاهيم واجهة المستخدم الرسومية ، والنص التشعبي ، وما إلى ذلك) من الستينيات حول أنظمة Open Hyper-Document (OHS) ، عندما لا يكون النظام مستندًا إلى المستندات ، ولكن واحد ، أي أنها تنفذ جميع عمليات النشاط البشري.
PS بشكل عام ، أفضل مشاهدة الفيديو.
سيعقد الاجتماع التالي ،
اكتب في Docs Moscow ، في 7 ديسمبر في مكتب التقنيات الإيجابية ، وسيعقد في شكل معركة أدوات التأليف الإيجابي.
