استخدم GIT عند التوثيق

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

النهج الموضح هنا ، مع مثال لتطبيق محدد ، له عتبة دخول منخفضة. تقنيًا ، غدًا ، يمكنك البدء في العمل بطريقة جديدة.

بيان المشكلة

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

1. ينطوي هذا العمل على عمل مشترك أو جهود مجموعة أو عدة مجموعات من الموظفين
2. في الإخراج ، تريد أن يكون لديك مستند بتنسيق معين ، مع سمات نمط الشركة ، التي تم إنشاؤها وفقًا لقالب معين. من أجل الدقة ، سوف نفترض أن هذا هو MS Word (.docx)

قبل 10 سنوات ، سيكون النهج لا لبس فيه: سنقوم بإنشاء مستند أو مستندات MS Word وتنظيم العمل على التغيير بطريقة أو بأخرى.

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

مثال

لقد شعرت بهذه المشكلة تمامًا أثناء العمل في وحدة دمج كبيرة واحدة. كانت عملية تغيير وثائق التصميم كما يلي:

1. يقوم مهندس بتحميل أحدث إصدار من مستند MS Word (.docx)
2. يغير الاسم
3. يجري تغييرات على وزارة الدفاع المسار
4. يرسل المستند مع تصحيحات إلى المهندس المعماري
5. يرسل أيضا قائمة بجميع التصحيحات مع التعليقات
6. مهندس يحلل التغيير
7. إذا كان كل شيء على ما يرام ، فقم بنسخ بيانات التغيير إلى الملف باستخدام أحدث إصدار ، وتغيير الإصدار ، ووضعه على مورد مشترك
8. إذا كانت هناك تعليقات ، فسيتم بدء المناقشة (البريد الإلكتروني أو المسيرات)
9. تم التوصل إلى توافق في الآراء
10. الفقرات الأخرى 3 - 9

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

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

في هذه الحالة ، فإن هذا النهج ، وهو أسلوب العمل على مستند MS Word ، قد عمل مع صرير كبير وخلق مشاكل.

بوابة تخفيض السعر

في مواجهة المشكلة الموضحة في المثال أعلاه ، بدأت في البحث في هذه المشكلة.
لقد رأيت أن استخدام تخفيض السعر مع Git أثناء إنشاء المستندات أصبح أكثر شيوعًا.

جيت هي أداة تطوير. ولكن لماذا لا تستخدمه في عملية التوثيق؟ في هذه الحالة ، يتم حل مشكلة العمل متعدد المستخدمين. ولكن من أجل الاستفادة الكاملة من ميزات Git ، نحتاج إلى تنسيق نصي للمستند ، نحتاج إلى إيجاد أداة أخرى ، وليس MS Word ، و Markdown رائع لهذه الأغراض.

تخفيض السعر هي لغة ترميز نصية بسيطة. وهو مصمم لإنشاء نصوص مصممة بشكل جميل في ملفات TXT العادية. إذا أنشأنا مستنداتنا في تخفيض السعر ، فسيبدو رابط "تخفيض السعر" أمرًا طبيعيًا.

وسيكون كل شيء على ما يرام ، وفي هذا المكان سيكون من الممكن وضع حد لو لم يكن ذلك بالنسبة للشرط الثاني لدينا: "في الإخراج نحتاج إلى مستند بتنسيق معين ، مع إنشاء سمات نمط الشركة وفقًا لقالب معين" (واتفقنا أولاً على ذلك من أجل اليقين ، سيكون MS Word). أي إذا قررنا استخدام تخفيض السعر ، فإننا نحتاج إلى تحويل هذا الملف بطريقة أو بأخرى إلى .docx من النوع المطلوب.

هناك برامج للتحويل بين تنسيقات مختلفة ، على سبيل المثال ، Pandoc .
يمكنك تحويل ملف Markdown إلى تنسيق .docx باستخدام هذا البرنامج.
ولكن لا يزال ، عليك أن تفهم أنه ، أولاً ، لن يتم تحويل كل ما هو موجود في برنامج تخفيض السعر إلى برنامج MS Word ، وثانياً ، يعد برنامج MS Word بلدًا كاملًا مقارنة بالمرهق ، ولكنه لا يزال مدينة صغيرة ، وهو برنامج تخفيض السعر. يوجد قدر كبير من كل شيء موجود في Word ولا يوجد بأي شكل في تخفيض السعر. لا يمكنك فقط اتخاذ تنسيق تخفيض السعر باستخدام مفاتيح Pandoc المطلوبة في الشكل المرغوب فيه لبرنامج MS Word. لذلك عادة ، بعد التحويل ، يجب عليك "تحسين" مستند docx الذي تم استلامه يدويًا ، والذي قد يستغرق وقتًا طويلًا ويؤدي إلى حدوث أخطاء.

إذا استطعنا كتابة نص سينهي تلقائيًا ما لا تستطيع Pandoc القيام به ، فسيكون حلاً مثاليًا.

نظرًا لحقيقة أن وظيفة MS Word و Markdown ليست متطابقة بعبارات عامة ، من المستحيل حل هذه المشكلة ، على ما أعتقد ، ولكن هل يمكن القيام بذلك فيما يتعلق بحالات معينة ومتطلبات محددة؟ لقد أثبتت تجربتي أنه نعم ، إنه أمر ممكن وعلى الأرجح أنه ممكن للعديد من الحالات ، أو ربما معظم الحالات.

حل مشكلة معينة

لذلك ، في حالتي ، بعد تحويل الملف باستخدام Pandoc ، اضطررت إلى القيام بمعالجة ملفات إضافية يدويًا ، وهي:

• إضافة الحقول في Word مع الترقيم التلقائي للتسميات التوضيحية للجداول والصور
• تغيير النمط للجداول

لم أجد كيفية القيام بذلك باستخدام معيار (Pandoc) أو وسائل معروفة. لذلك ، قمت بتطبيق برنامج نصي بيثون مع حزمة pywin32 . نتيجة لذلك ، حصلت على أتمتة كاملة. الآن يمكنني تحويل ملفي Markdown إلى الشكل المرغوب فيه من مستند MS Word باستخدام أمر واحد.

انظر التفاصيل هنا .

تعليق

في هذا المثال ، بالطبع ، سأقوم بتحويل بعض ملفات Markdown التجريدية ، ولكن تم تطبيق النهج نفسه تمامًا على المستند "القتالي" ، وفي الإخراج تلقيت تقريبًا نفس مستند MS Word ، الذي تلقيناه مسبقًا من خلال التنسيق اليدوي.

بشكل عام ، مع pywin32 ، نحصل على تحكم كامل تقريبًا في مستند MS Word ، والذي يسمح لنا بتغييره وجعله في الشكل الذي يتطلبه معيار شركتك. بالطبع ، يمكن تحقيق نفس الأهداف باستخدام أدوات أخرى ، على سبيل المثال ، وحدات ماكرو VBA ، لكن كان من الأنسب لي استخدام python.

صيغة موجزة لهذا النهج:

Markdown + Git -- () --> MS Word 

ليس مهم جدا ما هو "شيء". في حالتي ، كان Pandoc وثعبان مع pywin32. قد يكون لديك تفضيلات مختلفة ، ولكن الشيء المهم هو أن هذا ممكن. وهذه هي الرسالة الرئيسية لهذا المقال.

باختصار ، الفكرة هي أنه من خلال هذا النهج ، تعمل فقط مع ملف Markdown وتستخدم Git لتنظيم التعاون والتحكم في الإصدار ، وفقط إذا لزم الأمر (على سبيل المثال ، لتوفير الوثائق للعميل) إنشاء ملف التنسيق المطلوب تلقائيًا (على سبيل المثال ، MS Word ).

هذه العملية

أعتقد بالنسبة للكثيرين أن الصيغة المذكورة أعلاه كافية لفهم كيف يمكن تنظيم عملية العمل مع الوثائق الآن. لكن مع ذلك ، عادة ما أركز على مهندسي الشبكات ، لذلك سأوضح بشكل عام كيف يمكن أن تبدو العملية الآن وكيف تختلف عن النهج المتبع في تحرير ملفات MS Word.

للتأكد من صحتها ، سنختار GitHub كمنصة للعمل مع Git. ثم يجب عليك إنشاء مستودع ووضع ملف تخفيض السعر أو الملفات التي تخطط للعمل معها في الفرع الرئيسي.

سوف ننظر في عملية بسيطة تعتمد على تدفق جيثب. يمكن العثور على وصفه على الإنترنت وعلى موقع Habr .

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

بعد الانتهاء من بعض الأعمال المنجزة ، تقوم بتكوين طلب سحب ، وبذلك تبدأ مناقشة تغييراتك. ربما في عملية المناقشة ، اتضح أنه يجب عليك إضافة أو تغيير شيء آخر. في هذه الحالة ، يمكنك إجراء التغييرات اللازمة وإنشاء طلب سحب إضافي. في النهاية ، يتم قبول تغييراتك ودمجها مع الفرع الرئيسي (أو المرفوض).

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

ما هو استخدام هذا النهج في المقارنة ، على سبيل المثال ، مع العملية الموضحة في المثال أعلاه؟

في الواقع ، العمليات متشابهة إلى حد ما ، لقد استبدلت للتو

نسخ ملف -> إنشاء فرع
نسخ النص إلى الملف النهائي> دمج (دمج)
نسخ أحدث التغييرات على نفسك -> بوابة سحب / جلب
مناقشة في المراسلات -> سحب الطلبات
وضع المسار -> بوابة فرق
أحدث نسخة معتمدة -> فرع رئيسي
النسخ الاحتياطي (نسخ إلى خادم بعيد) -> بوابة دفع
...

وبالتالي ، قمت تلقائيًا بكل ما كان عليك فعله بالفعل ، ولكن يدويًا.

في مستوى أعلى ، وهذا يسمح لك

• إنشاء عملية واضحة وبسيطة والتحكم لتغيير الوثائق.
• ل المستند النهائي (في المثال الخاص بنا MS Word) الذي تنشئه تلقائيًا ، يقلل هذا من احتمال حدوث أخطاء متعلقة بالتنسيق

تعليق

في ضوء ما سبق ، أعتقد أنه من الواضح أنه حتى لو كنت تعمل على الوثائق وحدها ، فإن استخدام Git يمكن أن يسهل عملك إلى حد كبير

كل هذا يحسن جودة الوثائق ويقلل من الوقت لإنشائها. ومكافأة صغيرة - تتعلم Git ، والتي سوف تساعدك في أتمتة شبكتك :)

كيفية التحول إلى عملية جديدة؟

في بداية المقال ، كتبت أنه يمكنك غدًا البدء في العمل بطريقة جديدة. كيف تترجم عملك في اتجاه جديد؟

فيما يلي تسلسل الخطوات التي من المحتمل أن تكملها:

• إذا كان المستند كبيرًا جدًا ، قسّمه إلى أجزاء
• تحويل كل جزء إلى Markdown (باستخدام Pandoc ، على سبيل المثال)
• تثبيت أحد محرري Markdown (يمكنني استخدام Typora )
• على الأرجح سيكون عليك تعديل تنسيق مستندات Markdown التي تم إنشاؤها
• البدء في تطبيق العملية الموضحة في الفصل السابق
• بالتوازي ، ابدأ في تعديل برنامج التحويل ليناسب مهمتك (أو أنشئ شيئًا خاصًا بك)

ليس عليك الانتظار حتى تقوم بإنشاء وتصحيح آلية التحويل Markdwon -> المطلوبة لنوع مستند الإخراج. الحقيقة هي أنه حتى إذا لم تتمكن بسرعة من أتمتة تحويل ملفات Markdown بشكل سريع ، فلا يزال بإمكانك القيام بذلك بأي شكل من الأشكال باستخدام Pandoc ومن ثم إحضاره يدويًا إلى صورته النهائية. عادة لا تحتاج إلى القيام بذلك كثيرًا ، ولكن فقط في نهاية مراحل معينة ، وهذا العمل اليدوي ، على الرغم من أنه غير مريح ، لا يزال ، في رأيي ، مقبولًا تمامًا في مرحلة تصحيح الأخطاء ويجب ألا يبطئ العملية كثيرًا.

كل شيء آخر (تخفيض السعر ، Git ، Pandoc ، Typora) جاهز ولا يتطلب جهدا خاصا أو وقتا من أجل البدء في العمل معهم.