كيفية أتمتة سير عمل التوثيق للمطورين

لتحقيق أقصى استفادة من هذا البرنامج التعليمي ، يجب أن تكون على دراية بـ: Git و GitHub و Linux وسطر الأوامر.

لماذا يجب أن تهتم بالوثائق عالية الجودة؟

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

يضر التوثيق السيئ أيضًا بتجربة العميل الجيدة. وفقًا لجيف لوسون ، مؤلف Ask Your Developer ومؤسس Twilio ، إذا كنت تبيع واجهة برمجة تطبيقات كمنتج ، فإن التوثيق هو الإعلان النهائي لأصحاب المصلحة التقنيين . أجرت شركة IBM دراسة حول أهمية التوثيق ، واعترف 90٪ من المستجيبين بأنهم اتخذوا قرارات الشراء الخاصة بهم بناءً على جودة وثائق المنتج.

تعد كتابة التوثيق الجيد أمرًا مهمًا للمطور وتجارب العملاء.

إذا كان التوثيق مهمًا جدًا ، فلماذا إذن ترفضه فرق الهندسة؟

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

أتمتة التوثيق وتحسين سير عمل التوثيق يعمل على إصلاح هذا.

أتمتة التوثيق من مستوى عال

ماذا تعني أتمتة التوثيق؟ إنه يعني تبني ممارسات تطوير البرمجيات المشتركة. عندما تقوم بأتمتة التوثيق ، فأنت:

• كتابة وثائقك في Markdown ؛
• استخدام خط أنابيب للتكامل المستمر والنشر المستمر (CI / CD) لتشغيل مهام مثل تصحيح الأخطاء ونشر التحديثات (في هذا البرنامج التعليمي ، سنقوم بتسليط الضوء على إجراءات GitHub) ؛
• تنفيذ أدوات مثل Vale لفرض دليل أسلوب وتصحيح الأخطاء النحوية الشائعة.

دليل الاسلوب

قبل استخدام أدوات مثل Vale و GitHub Actions لأتمتة دليل النمط ، دعنا نتوقف لحظة لتحديد ما هو بالضبط دليل النمط.

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

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

TAPP هو تطبيق ترانزيت (للحافلات والقطارات). يعلن عنوان الجدول عن قيم TAPP كشركة ، كونها فعالة وجديرة بالثقة ويمكن الوصول إليها. يسرد الجانب الأيسر من الجدول الأجزاء المختلفة التي يغطيها دليل النمط: المفاهيم ، والمفردات ، والإسهاب ، والقواعد ، وعلامات الترقيم.

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

دليل أسلوب الكتابة الفنية

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

المشكلة مع أدلة الأسلوب

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

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

Linters و CI / CD للتوثيق

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

يعد استخدام نوع من أتمتة التوثيق جنبًا إلى جنب مع linter أمرًا شائعًا. عندما نقول الأتمتة في هذا السياق ، فإننا نشير إلى سير عمل التكامل المستمر والنشر المستمر (CI / CD). تقوم CI بأتمتة بناء واختبار الوثائق . القرص المضغوط بأتمتة إصدار الكود.

يمكنك استخدام العديد من أنواع التطبيقات المختلفة لتنفيذ سير عمل CI / CD. في هذا البرنامج التعليمي ، سنستخدم إجراءات GitHub لتشغيل وثائقنا linter. تقوم GitHub Actions بتشغيل CI مباشرة في مستودع GitHub ، لذلك ليست هناك حاجة لاستخدام تطبيق تابع لجهة خارجية ، مثل CircleCI أو Travis.

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

إجراءات جيثب

أولاً ، قم بإنشاء مستودع GitHub. ثم ، محليًا ، أنشئ مجلدًا cd .

 mkdir automated-docs cd automated-docs

بمجرد أن تكون في المجلد ، قم بتهيئة دليل Git.

 git init

بمجرد قيامك بتهيئة المستودع ، تابع إنشاء دليل مسار العمل إلى المجلد الخاص بك.

 mkdir .github/ && cd .github/ && mkdir workflows/ && cd workflows/

مهام سير العمل هي المكان الذي سنخزن فيه جميع إجراءات GitHub الخاصة بنا. بمجرد إنشاء مجلد workflows ، قم بإنشاء سير عمل جديد. سنقوم بتسمية سير العمل vale.yml .

 touch vale.yml

Vale.yml هو ملف YAML. في ملف سير العمل هذا ، سنقوم بتضمين الإجراءات والوظائف.

الآن ، افتح vale.yml في محرر النصوص المفضل لديك.

 nano vale.yml

انسخ والصق ما يلي في vale.yml ، ودعنا ننتقل إلى السياق وبناء الجملة.

 # This is a basic workflow to help you get started with Actions name: CI # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project. env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

• name
  هذا هو الاسم ، أو ما نسميه سير العمل لدينا. إنها سلسلة.
• on
  هذا يتحكم في سير العمل والمشغلات.
• jobs
  هذا هو المكان الذي نؤسس فيه أعمالنا ونتحكم فيها. نختار البيئة التي ستعمل فيها أفعالنا - عادة ما يكون رهانًا جيدًا للذهاب مع Ubuntu. وهذا هو المكان الذي سنضيف فيه أفعالنا.

يحتوي GitHub على دليل حول جميع صيغ ومتغيرات سير العمل الأخرى ، في حال كنت فضوليًا.

في هذا القسم لدينا:

• تعلمت ما هي إجراءات جيثب ،
• أنشأنا أول سير عمل على GitHub ،
• حددت أهم أجزاء ملف YAML لسير عمل GitHub.

بعد ذلك ، سنقوم بتخصيص سير عمل GitHub الخاص بنا لاستخدام Vale.

قم بإعداد Vale in GitHub Actions File

بمجرد نسخ ملف سير العمل الأساسي ، حان الوقت لتخصيصه ، حتى نتمكن من البدء في استخدام إجراءات Vale. أول شيء يجب فعله هو تغيير اسم ملف YAML إلى Docs-Linting .

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting

بعد ذلك ، نريد إجراء اختبار Vale بمجرد قيام شخص ما بدفع تغييراته إلى الفرع الرئيسي على GitHub. لا نريد تشغيل الاختبار عندما يقوم شخص ما بإنشاء طلب سحب ، لذلك سنحذف هذا الجزء من ملف YAML.

 on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ]

قسم jobs هو الجزء الرئيسي من ملف سير العمل ، وهو مسؤول عن تشغيل إجراءات GitHub.

 jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master

سيتم تشغيل هذه الإجراءات على أحدث إصدار من Ubuntu. يقوم إجراء Checkout بفحص المستودع حتى يتمكن سير عمل GitHub من الوصول إليه.

حان الوقت الآن لإضافة إجراء Vale إلى سير عمل GitHub الخاص بنا.

 - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

لقد أطلقنا على عملنا اسم Vale . يوضح متغير uses إصدار Vale الذي سنقوم بتطبيقه - من الناحية المثالية ، يجب أن نستخدم أحدث إصدار. في المتغير with ، قمنا بتعيين debug على true .

يمنحنا قسم styles خيار إضافة دليل نمط إلى Vale. في هذا المثال ، سنستخدم أسلوب write-good ودليل الأسلوب الرسمي من Microsoft. ضع في اعتبارك أنه يمكننا استخدام أدلة نمط أخرى أيضًا.

الجزء الأخير من إجراء GitHub هو env . لتشغيل إجراء GitHub هذا ، نحتاج إلى تضمين رمز مميز سري.

هذا ما يجب أن تبدو عليه النتيجة:

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: jobs: prose: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

بمجرد الانتهاء من إجراء التغييرات ، احفظ الملف ، والتزم بـ Git ، وادفع التغييرات إلى GitHub.

 git add .github/workflows/vale.yml git commit -m "Added github repo to project" git push -u origin main

للتلخيص ، في هذا القسم ، لدينا:

• تسبب في حدوث الإجراء عندما ندفع رمزًا جديدًا إلى الفرع main ؛
• أضاف إجراء Vale ، مع ضبط debug على أدلة الأسلوب true وتحديدها ؛
• تمت إضافة رمز GitHub ؛
• التغييرات التي ارتكبت وتم دفعها إلى GitHub.

في القسم التالي ، سننشئ ملف تكوين Vale.

إعداد ملف تكوين Vale

انتقل إلى جذر دليل مشروعك ، ثم touch .vale.ini . افتح .vale.ini في محرر نصي. انسخ ما يلي والصقه في .vale.ini :

 StylesPath = .github/styles MinAlertLevel = warning [formats] Markdown = markdown [*.md] BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
  يعطي StylesPath مسار أنماط Vale.
• MinAlertLevel = warning
  يُظهر مستوى التنبيه الأدنى مقياس الخطورة في التنبيهات. الخيارات هي suggestion warning error .
• [formats]
Markdown = markdown يحدد التنسيق على أنه Markdown.
• [*.md]
  التكوين BasedOnStyles = write-good, Microsoft بتشغيل دليل أسلوب الكتابة الجيد و Microsoft على جميع ملفات Markdown التي تنتهي بـ .md .

هذا الترتيب هو الحد الأدنى. إذا كنت مهتمًا بمعرفة المزيد حول تكوين Vale ، فانتقل إلى الوثائق.

عند الانتهاء من إجراء التغييرات ، احفظ الملف ، وقم بالالتزام والدفع إلى GitHub.

 git add .vale.ini git commit -m "Added Vale config file" git push -u origin main

في هذا الجزء ، تعلمنا العناصر الداخلية لملف تكوين Vale. حان الوقت الآن لإنشاء نموذج التوثيق.

إنشاء الوثائق والبدء في إجراءات Vale GitHub

حان الوقت الآن لمشاهدة إجراءات Vale و GitHub قيد التنفيذ! سننشئ ملف Markdown ونملأه بالنص. وسوف نحصل على نصنا من DeLorean Ipsum.

انتقل إلى جذر مشروعك ، ثم touch getting-started.md . بمجرد إنشاء ملف getting-started ، انتقل إلى DeLorean Ipsum وقم بإنشاء بعض النصوص الوهمية لوثائقك. ثم ارجع إلى محرر النصوص والصق النص في getting-started-md .

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all exactly twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

احفظ الملف وقم بتثبيته وادفعه إلى GitHub.

 git add getting-started.md git commit -m "first draft" git push -u origin main

بمجرد دفع التغييرات ، توجه إلى GitHub حيث يوجد مستودعك. انتقل إلى علامة التبويب Actions .

سترى جميع مهام سير العمل الخاصة بك على الجانب الأيسر. لدينا واحد فقط ، اسمه Docs-Linting ، وهو نفس الاسم الذي وضعناه في ملف vale.yml .

عندما نقوم بدفع الوثائق إلى GitHub ، سنقوم بتشغيل الإجراء.

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

انقر فوق "المستندات المضافة" للحصول على تقرير كامل.

سترى أننا تلقينا 11 تحذيرًا. دعونا نتعامل مع تحذير "كلمة ابن عرس". ارجع إلى محرر النصوص ، وافتح getting-started.md ، واحذف كلمة "بالضبط".

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

احفظ التغييرات ، وألزمها بـ Git ، وادفع الإصدار الجديد من الملف إلى GitHub. يجب أن يقوم بتشغيل إجراء GitHub .

إذا نقرنا على "حذف كلمة ابن عرس" ، فسنرى أن لدينا 10 تحذيرات فقط الآن ، وسيختفي تحذير "كلمة ابن عرس". الصيحة!

لقد انتهينا ، وغطينا الكثير من الأرضية. في هذا القسم لدينا:

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

خاتمة

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

يجب التعامل مع الوثائق مثل قاعدة الشفرة الخاصة بك: مجموعة عمل حية يتم تكرارها باستمرار وتصبح أفضل قليلاً من آخر مرة قمت فيها بتحديثها.