วิธีทำให้เวิร์กโฟลว์เอกสารสำหรับนักพัฒนาเป็นแบบอัตโนมัติ

เพื่อให้ได้ประโยชน์สูงสุดจากบทช่วยสอนนี้ คุณควรทำความคุ้นเคยกับ: Git, GitHub และ Linux และบรรทัดคำสั่ง

ทำไมคุณจึงควรใส่ใจเกี่ยวกับเอกสารคุณภาพสูง?

หลายทีมประสบปัญหาใน การเขียนเอกสาร เมื่อคุณไปตรวจสอบกรอบงาน เอกสารมักจะล้าสมัยหรือไม่ชัดเจน ซึ่งอาจนำไปสู่ความคับข้องใจภายในเมื่อสมาชิกในทีมพยายามเพิ่มคุณลักษณะ แต่พวกเขาไม่เข้าใจว่าคุณลักษณะปัจจุบันทำงานอย่างไรเนื่องจากเอกสารประกอบไม่ดี ซึ่งอาจนำไปสู่ชั่วโมงการทำงานที่ไม่เกิดผล

เอกสารที่ไม่ดียังส่งผลต่อประสบการณ์ที่ดีของลูกค้า ตามที่ Jeff Lawson ผู้เขียน Ask Your Developer และผู้ก่อตั้ง Twilio กล่าว หากคุณกำลังขาย API เป็นผลิตภัณฑ์ เอกสารประกอบเป็น โฆษณาขั้นสุดท้ายสำหรับผู้มีส่วนได้ส่วนเสียด้านเทคนิค IBM ได้ทำการศึกษาเกี่ยวกับความสำคัญของเอกสาร และ 90% ของผู้ตอบแบบสอบถามยอมรับว่าพวกเขาตัดสินใจซื้อโดยพิจารณาจากคุณภาพของเอกสารประกอบของผลิตภัณฑ์

การเขียนเอกสารที่ดีเป็นสิ่งสำคัญสำหรับนักพัฒนาและประสบการณ์ของลูกค้า

หากเอกสารมีความสำคัญมาก ทำไมทีมวิศวกรถึงลดความสำคัญลง?

การเขียนเอกสารสามารถแบ่งนักพัฒนาออกจาก "โฟลว์" เอกสาร มักจะอยู่นอกฐานรหัสหลัก และเป็นการยากที่จะค้นหาและอัปเดต การใส่ลงในสเปรดชีต Excel หรือ CMS ที่เป็นกรรมสิทธิ์นั้นไม่ใช่เรื่องแปลก

การทำเอกสารอัตโนมัติและปรับปรุงเวิร์กโฟลว์เอกสารช่วยแก้ไขปัญหานี้ได้

จัดทำเอกสารอัตโนมัติจากระดับสูง

เอกสาร อัตโนมัติ หมายถึงอะไร หมายถึงการนำแนวทางการพัฒนาซอฟต์แวร์ทั่วไปมาใช้ เมื่อคุณทำให้เอกสารเป็นอัตโนมัติ คุณคือ:

• เขียนเอกสารของคุณใน Markdown;
• การใช้ไปป์ไลน์การผสานรวมอย่างต่อเนื่องและการปรับใช้อย่างต่อเนื่อง (CI/CD) เพื่อรันงานต่างๆ เช่น การแก้ไขข้อผิดพลาดและการปรับใช้การอัปเดต (ในบทช่วยสอนนี้ เราจะเน้นที่การดำเนินการของ GitHub)
• การใช้เครื่องมือเช่น Vale เพื่อบังคับใช้คู่มือสไตล์และแก้ไขข้อผิดพลาดทางไวยากรณ์ทั่วไป

คู่มือสไตล์

ก่อนที่คุณจะใช้เครื่องมือ เช่น Vale และ GitHub Actions เพื่อทำให้คู่มือสไตล์เป็นแบบอัตโนมัติ เรามาใช้เวลาสักครู่เพื่อกำหนดว่าคู่มือสไตล์คืออะไรกันแน่

คุณทราบความรู้สึกนั้นเมื่อเขียนเอกสารและดูเหมือนมีอะไรผิดปกติไหม? คำอธิบายของคุณไม่พอดีกับเอกสารที่เหลือ แต่คุณไม่สามารถอธิบายได้ว่าทำไมจึงผิด การเขียนอธิบายแนวความคิด แต่ดูเหมือนจะไม่เหมาะ

เมื่อคุณได้รับความรู้สึกนี้ เสียงและโทนของคุณอาจจะปิด การปรับแต่งเสียงและโทนเป็นวิธีหนึ่งที่จะทำให้การเขียนมีความสอดคล้องกัน แม้ว่าคุณจะกำลังพัฒนาเอกสารที่ได้รับการแก้ไขโดย QA, ฝ่ายวิศวกรรม และผลิตภัณฑ์แล้วก็ตาม ด้านล่างนี้คือตัวอย่างคำแนะนำรูปแบบจากแอปพลิเคชั่นรถโดยสารประจำทาง TAPP ที่นำมาจากหนังสือ Strategic Writing for UX โดย Torrey Podmajersky

TAPP เป็นแอปพลิเคชั่นขนส่ง (สำหรับรถโดยสารและรถไฟ) ส่วนหัวของตารางประกาศค่านิยมของ TAPP ในฐานะบริษัท มีประสิทธิภาพ เชื่อถือได้ และเข้าถึงได้ ด้านซ้ายของตารางแสดงรายการส่วนต่างๆ ที่ครอบคลุมโดยคำแนะนำรูปแบบ ได้แก่ แนวคิด คำศัพท์ การใช้คำฟุ่มเฟือย ไวยากรณ์ และเครื่องหมายวรรคตอน

สิ่งเหล่านี้ทำให้เป็น แนวทางสไตล์ ส่วนหัวจะแนะนำค่าต่างๆ และด้านซ้ายของตารางจะแสดงองค์ประกอบต่างๆ ที่คุณจะพบในเอกสารที่เป็นลายลักษณ์อักษร เช่น คำศัพท์ ไวยากรณ์ และเครื่องหมายวรรคตอน ความงามของคู่มือสไตล์นี้คือวิศวกรและนักเขียนคำโฆษณาจะทราบอย่างชัดเจนว่าควรใช้อักษรตัวพิมพ์ใหญ่ใดและใช้เครื่องหมายวรรคตอนใดเพื่อส่งเสริมเอกลักษณ์แบรนด์ของ Tapp

คู่มือรูปแบบการเขียนทางเทคนิค

คู่มือสไตล์บางรายการไม่ได้มาในตาราง Microsoft มีเว็บไซต์ทั้งหมดที่ทำหน้าที่เป็นคู่มือที่ครอบคลุม ครอบคลุมทุกอย่างตั้งแต่ตัวย่อ การสื่อสารที่ปราศจากอคติ ไปจนถึงแชทบอท แน่นอนว่า Microsoft ไม่ใช่บริษัทเดียวที่มีคู่มือสไตล์ Google ก็มีเช่นกัน

ปัญหากับคำแนะนำสไตล์

คู่มือรูปแบบเป็นจุดเริ่มต้นที่ดีสำหรับบริษัทที่จริงจังเกี่ยวกับเอกสาร พวกเขาแก้ปัญหาความสับสนมากมายที่นักพัฒนาอาจมีเกี่ยวกับวิธีการเขียนเกี่ยวกับคุณสมบัติหลักที่พวกเขากำลังเผยแพร่

ปัญหาของ style guides คือการที่มันเพิ่มความเสียดทานให้กับกระบวนการเขียน นักเขียนหลายคนรวมถึงฉันด้วย ไม่หยุดเขียนและดูคู่มือสไตล์ทุกครั้งที่มีคำถาม บางครั้ง คู่มือสไตล์ก็ดูยุ่งยากและยากเกินไปที่จะอ้างอิง ตัวอย่างเช่น คู่มือสไตล์ของ Microsoft มีความยาวมากกว่าหนึ่งพันหน้า!

Linters และ CI/CD สำหรับเอกสาร

หากคุณเป็นโปรแกรมเมอร์ คุณอาจคุ้นเคยกับ Linters Linters เป็นวิธีที่เหมาะที่สุดในการ บังคับใช้มาตรฐานการเข้ารหัส ในทีมของคุณ เช่นเดียวกับเอกสาร เมื่อคุณสร้าง linter คุณกำลังตั้งค่ามาตรฐานคุณภาพสำหรับเอกสารของคุณ ในบทช่วยสอนนี้ เราจะใช้ Vale linter

การใช้เอกสารอัตโนมัติบางประเภทควบคู่ไปกับ linter เป็นเรื่องปกติ เมื่อเราพูดถึงระบบอัตโนมัติในบริบทนี้ เราหมายถึงเวิร์กโฟลว์การผสานรวมอย่างต่อเนื่องและการปรับใช้อย่างต่อเนื่อง (CI/CD) CI ดำเนินการ สร้างและทดสอบเอกสาร โดยอัตโนมัติ ซีดีจะปล่อยรหัสโดยอัตโนมัติ

คุณสามารถใช้แอปประเภทต่างๆ เพื่อใช้เวิร์กโฟลว์ CI/CD ได้ ในบทช่วยสอนนี้ เราจะใช้ GitHub Actions เพื่อเรียกใช้เอกสาร linter GitHub Actions เรียกใช้ CI โดยตรงในที่เก็บ GitHub ดังนั้นจึงไม่จำเป็นต้องใช้แอปพลิเคชันของบุคคลที่สาม เช่น CircleCI หรือ Travis

สุดท้าย GitHub Actions เป็น event-driven ซึ่งหมายความว่าจะมีการทริกเกอร์เมื่อมีบางอย่างเกิดขึ้น เช่น เมื่อมีคนเขียนคำขอดึงหรือปัญหา ในตัวอย่างของเรา การกระทำของ GitHub จะเกิดขึ้นเมื่อมีคนพุชการเปลี่ยนแปลงไปยังสาขาหลักของตน

GitHub Actions

ขั้นแรก สร้างที่เก็บ 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
  นี่คือที่ที่เราตั้งค่าและควบคุมการกระทำของเรา เราเลือกสภาพแวดล้อมที่การกระทำของเราจะดำเนินการ — มักจะเป็นทางเลือกที่ดีที่จะใช้อูบุนตู และนี่คือที่ที่เราจะเพิ่มการกระทำของเรา

GitHub มีคำแนะนำเกี่ยวกับไวยากรณ์และตัวแปรของเวิร์กโฟลว์อื่นๆ ทั้งหมด ในกรณีที่คุณอยากรู้

ในส่วนนี้ เรามี:

• เรียนรู้ว่าการกระทำของ GitHub คืออะไร
• สร้างเวิร์กโฟลว์ GitHub แรกของเรา
• ระบุส่วนที่สำคัญที่สุดของไฟล์ YAML เวิร์กโฟลว์ GitHub

ต่อไป เราจะปรับแต่งเวิร์กโฟลว์ GitHub ของเราเพื่อใช้ Vale

ตั้งค่า Vale ใน 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 ตัวแปร use 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 Actions

ถึงเวลาที่จะได้เห็นการกระทำของ 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 Actions ของเรา
• กระตุ้นการกระทำของ Vale GitHub
• แก้ไขข้อผิดพลาดที่เกิดจาก Vale และผลักดันการเปลี่ยนแปลงกลับไปที่ GitHub

บทสรุป

ในโลกที่ห่างไกลมากขึ้น การจัดลำดับความสำคัญของ เอกสาร ที่ดีและเวิร์กโฟลว์เอกสารที่ดีเป็นสิ่งสำคัญ ก่อนอื่นคุณต้องกำหนดว่า "ดี" คืออะไรโดยการสร้างคู่มือสไตล์ เมื่อคุณเข้าใจกฎของเอกสารแล้ว ก็ถึงเวลาที่ต้องทำให้เป็นระบบอัตโนมัติ

เอกสารควรได้รับการปฏิบัติเหมือนเป็นฐานรหัสของคุณ: เนื้อหาที่มีชีวิตซึ่งมีการทำซ้ำอย่างต่อเนื่องและดีขึ้นเล็กน้อยกว่าครั้งล่าสุดที่คุณอัปเดต