ในการเขียนเอกสารผลิตภัณฑ์หรือเอกสารทางเทคนิค สิ่งสำคัญคือการจัดโครงสร้างเนื้อหาให้ชัดเจนและนำเสนอด้วยภาพในลักษณะที่ใช้งานง่าย สิ่งนี้ช่วยให้ผู้อ่านเข้าใจประเด็นสำคัญได้อย่างรวดเร็วและลดความพยายามที่จำเป็นในการทำความเข้าใจเนื้อหา
Apidog ในฐานะเครื่องมือจัดการ API ไม่เพียงแต่ช่วยให้การจัดการเอกสาร API มีประสิทธิภาพเท่านั้น แต่ยังช่วยให้ทีมสามารถสร้างเอกสารผลิตภัณฑ์ระดับมืออาชีพโดยใช้ไวยากรณ์ Markdown ที่ยืดหยุ่นได้อีกด้วย เอกสารช่วยเหลือ Apidog สำหรับผู้ใช้สร้างขึ้นโดยใช้คุณสมบัติ Markdown ของ Apidog
ด้านล่างนี้คือ 10 เคล็ดลับที่เป็นประโยชน์สำหรับการเขียนเอกสารผลิตภัณฑ์ด้วย Markdown ใน Apidog
1. ปรับแต่งชื่อแถบด้านข้าง
เมื่อคุณสร้างเอกสาร Markdown ใหม่ใน Apidog ชื่อในเอกสาร Markdown จะถูกใช้เป็นชื่อแถบด้านข้างโดยค่าเริ่มต้น ดังที่แสดงด้านล่าง:
หากคุณต้องการให้ชื่อแถบด้านข้างและชื่อเอกสารแตกต่างกัน คุณสามารถปรับแต่งแยกกันได้
ตัวอย่างเช่น คุณสามารถใช้ "Overview" เป็นชื่อแถบด้านข้าง และตั้งชื่อเอกสารให้เฉพาะเจาะจงมากขึ้น เช่น "Design APIs in Apidog"
วิธีการตั้งค่า: ภายในเอกสาร Markdown ให้คลิก "Sidebar Title" และแก้ไขชื่อ
การใช้ชื่อที่แตกต่างกันสำหรับแถบด้านข้างและเอกสารมีประโยชน์สองประการ:
- ชื่อแถบด้านข้างจะสั้นและเรียบร้อย ทำให้โครงสร้างโฟลเดอร์สะอาดตา
- ชื่อเอกสารสามารถมีรายละเอียดและอธิบายได้มากขึ้นเพื่อความชัดเจน
เมื่อคุณแชร์ลิงก์เอกสารบนแพลตฟอร์มอย่าง Slack ชื่อเอกสารจะปรากฏในการแสดงตัวอย่าง ทำให้ลิงก์ดูชัดเจนและเข้าใจง่ายขึ้น นี่คือตัวอย่างลักษณะที่ปรากฏใน Slack:
2. อ้างอิงทรัพยากรโปรเจกต์และสคีมา
Apidog ทำให้ง่ายต่อการอ้างอิง endpoint, เอกสาร และสคีมาจากโปรเจกต์ของคุณโดยตรงในไฟล์ Markdown
หากต้องการอ้างอิง endpoint และเอกสาร Markdown:
- เปิดเอกสาร Markdown ของคุณแล้วคลิก "Insert Endpoint/Markdown in the project"
- เลือกทรัพยากรที่คุณต้องการแทรก (endpoint หรือเอกสาร Markdown)
เนื้อหาที่อ้างอิงจะเชื่อมโยงกับทรัพยากรเป้าหมายในโปรเจกต์โดยอัตโนมัติ และการคลิกที่เนื้อหานั้นในมุมมองแสดงตัวอย่างจะนำไปสู่หน้ารายละเอียดนั้น
หากต้องการอ้างอิงสคีมา:
- ไปที่ "Insert" → "Data Schema"
- เลือกรายการที่ต้องการ
การเปลี่ยนแปลงใดๆ ที่ทีมของคุณทำกับ Data Schema จะซิงค์กับเวอร์ชันที่อ้างอิงโดยอัตโนมัติ ทำให้มั่นใจว่าเอกสารของคุณเป็นปัจจุบันอยู่เสมอ สิ่งนี้ช่วยป้องกันความสับสนและข้อผิดพลาดที่เกิดจากข้อมูลที่ล้าสมัย
ตัวอย่างโค้ด:
<DataSchema id="4700682" />
3. ควบคุมพฤติกรรมลิงก์และการนำทาง
Apidog Markdown รองรับประเภทลิงก์ที่หลากหลาย และพฤติกรรมของลิงก์เหล่านั้นในเอกสารออนไลน์จะแตกต่างกันไป:
- ลิงก์บางรายการเปิดใน แท็บเบราว์เซอร์ใหม่
- บางลิงก์เปิดใน หน้าปัจจุบัน
- ส่วนอื่น ๆ จะกระโดดไปยัง ส่วนเฉพาะ ในเอกสารโดยใช้ anchor
การเลือกประเภทลิงก์ที่เหมาะสมจะทำให้การนำทางง่ายขึ้นและช่วยให้ผู้ใช้ค้นหาข้อมูลที่ต้องการได้อย่างรวดเร็ว
ด้านล่างนี้ คุณจะพบรายละเอียดเกี่ยวกับวิธีการทำงานของลิงก์แต่ละประเภทและวิธีการกำหนดค่า
3.1 ลิงก์ที่เปิดในหน้าปัจจุบัน
ลิงก์ที่เพิ่มผ่าน "Insert Endpoint/Markdown in the project" จะสร้างที่อยู่เริ่มต้นด้วย apidog://link/pages/... ซึ่งจะเปิดในหน้าเบราว์เซอร์ปัจจุบันเมื่อคลิก
ตัวอย่างเช่น:
[Overview](apidog://link/pages/990068)
วิธีการตั้งค่า: คลิกปุ่ม "Insert Endpoint/Markdown in the project" และเลือก endpoint หรือเอกสารที่ต้องการ
ลิงก์เช่น apidog://link/pages/... สามารถใช้เป็นลิงก์ปกติใน Apidog Markdown ได้ หลังจากเผยแพร่หรือแชร์ ลิงก์เหล่านี้จะถูกแปลงเป็นที่อยู่เว็บจริงโดยอัตโนมัติ (เช่น https://xxx.apidog.io/xxx) และรองรับการกระโดดไปยังหน้าเป้าหมาย ตัวอย่างเช่น ในคอมโพเนนต์ "Card":
<Card title="Click here" href="apidog://link/pages/990068">
This is a card, click to jump to the target page
</Card>
3.2 ลิงก์ที่เปิดในแท็บใหม่
ลิงก์ใดๆ ที่ไม่ได้เพิ่มผ่าน "Insert Endpoint/Markdown in the project" จะเปิดในแท็บเบราว์เซอร์ใหม่โดยค่าเริ่มต้น ตัวอย่างเช่น:
[API-design first approach](https://docs.apidog.com/api-design-first-approach-533942m0)
3.3 Anchor Link ที่เปิดในแท็บใหม่
หากต้องการลิงก์โดยตรงไปยังส่วนเฉพาะในสารบัญ (TOC) ให้เพิ่ม anchor (เช่น #xxx) ที่ส่วนท้ายของลิงก์ของคุณ ตัวอย่างเช่น:
[these methods are the same as those used for inviting users to the team](https://docs.apidog.com/managing-team-members-613028m0#invitation-methods)
3.4 Anchor Link ที่เปิดในหน้าปัจจุบัน
คุณยังสามารถใช้ anchor ในลิงก์โปรเจกต์ภายในเพื่อกระโดดไปยังส่วนเฉพาะภายในเอกสารเดียวกันได้ ตัวอย่างเช่น:
[these methods are the same as those used for inviting users to the team](apidog://link/pages/613028#invitation-methods)
Anchor link เช่น apidog://link/pages/613028#invitation-methods จะทำงานหลังจากที่หน้าเว็บถูกแชร์หรือเผยแพร่แล้วเท่านั้น หากคุณคลิกลิงก์เหล่านี้ใน Apidog client ก่อนการเผยแพร่ จะไม่มีอะไรเกิดขึ้น เนื่องจากลิงก์ยังไม่ได้ถูกแปลงเป็นพาธเว็บที่เข้าถึงได้
ลิงก์ข้างต้นสามารถอยู่ในรูปแบบ Markdown หรือ HTML ก็ได้ ตัวอย่างเช่น:
Link that opens in the current page:
<a href="apidog://link/pages/533969">Design APIs in Apidog</a>
Link that opens in a new tab:
<a href="https://docs.apidog.com/design-apis-in-apidog-533969m0">Design APIs in Apidog</a>
Anchor link (opens in a new tab):
<a href="https://docs.apidog.com/design-apis-in-apidog-533969m0#design-apis">Design APIs in Apidog</a>
Anchor link (opens in the current page):
<a href="apidog://link/pages/533969#design-apis">Design APIs in Apidog</a>`4. สร้างเลย์เอาต์แบบเคียงข้างกันด้วย Container และ Column
เมื่อคุณต้องการแสดงความแตกต่างระหว่างเวอร์ชัน การเปรียบเทียบคุณสมบัติ หรือข้อมูลที่ขนานกัน ให้ใช้คอมโพเนนต์ "Container" ที่ซ้อนกับคอมโพเนนต์ "Column" เพื่อสร้างเลย์เอาต์แบบเคียงข้างกันที่โดดเด่นสะดุดตา
เลย์เอาต์นี้ช่วยให้ผู้อ่านเปรียบเทียบเนื้อหาได้อย่างง่ายดายในพริบตา ปรับปรุงความชัดเจนและการสื่อสาร
ตัวอย่างเช่น:
วิธีการตั้งค่า: ในเอกสาร Markdown ให้เลือก "Container" จากนั้น "Multiple columns → 2 columns" คุณสามารถเติมเนื้อหาในแต่ละคอลัมน์ได้ เช่น คำอธิบาย “Old Version” และ “New Version”
ตัวอย่างไวยากรณ์ Markdown:
<Container>
<Columns>
<Column>
**Old Version**
</Column>
<Column>
**New Version**
</Column>
</Columns>
---
<Columns>
<Column>
Here is the old version content
<DataSchema id="4700681" />
</Column>
<Column>
Here is the new version content
<DataSchema id="8144258" />
</Column>
</Columns>
</Container>💡 ใน Markdown ข้างต้น <DataSchema id="xxxxxx" /> หมายถึงสคีมาในโปรเจกต์
5. ใช้คอมโพเนนต์ Step เพื่อการแนะนำด้วยภาพ
สำหรับบทช่วยสอนเชิงปฏิบัติหรือคู่มือคุณสมบัติ ให้ใช้คอมโพเนนต์ "Step" ใน Apidog Markdown เพื่อแบ่งกระบวนการที่ซับซ้อนออกเป็นขั้นตอนที่ง่ายและทำตามได้ง่าย
การออกแบบที่มีคำแนะนำนี้ช่วยลดความสับสนของผู้ใช้และเพิ่มอัตราความสำเร็จ โดยเฉพาะอย่างยิ่งสำหรับผู้ใช้ใหม่หรือเมื่ออธิบายคุณสมบัติที่ซับซ้อน
คอมโพเนนต์ "Step" จะกำหนดหมายเลขแต่ละขั้นตอนโดยอัตโนมัติและเพิ่มสัญญาณภาพเพื่อให้กระบวนการชัดเจนและน่าสนใจ
ตัวอย่างเช่น:
วิธีการตั้งค่า: ในเอกสาร Markdown ให้เลือกคอมโพเนนต์ "Step" และป้อนเนื้อหาโดยละเอียดสำหรับแต่ละขั้นตอน
ตัวอย่างไวยากรณ์ Markdown:
<Steps>
<Step title="First Step">
These are instructions or content that only pertain to the first step.
</Step>
<Step title="Second Step">
These are instructions or content that only pertain to the second step.
</Step>
<Step title="Third Step">
These are instructions or content that only pertain to the third step.
</Step>
</Steps>
6. ปรับปรุงการแสดงผลและเลย์เอาต์รูปภาพ
ใน Apidog Markdown การแทรกรูปภาพทำได้ง่าย คุณสามารถอัปโหลดรูปภาพจากคอมพิวเตอร์ของคุณหรือวางลงในโปรแกรมแก้ไขได้โดยตรง
ลิงก์รูปภาพสามารถมาจาก CDN ของบุคคลที่สามได้ เช่น:
รองรับทั้งไวยากรณ์ Markdown และ HTML สำหรับการแทรกรูปภาพ ตัวอย่างเช่น:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog"/>ด้วย HTML คุณสามารถเพิ่มสไตล์ CSS แบบอินไลน์ได้ เช่น การระบุความกว้าง ความสูง และการจัดกึ่งกลาง:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="width: 400px;display: block; margin: 0 auto"/>
// or
<div style="text-align: center;">
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="width: 400px;" />
</div>ในโหมดมืด หากรูปภาพมีความโปร่งใส พื้นหลังจะแสดงเป็นสีขาวโดยค่าเริ่มต้น หากต้องการลบพื้นหลังสีขาว ให้ใช้ CSS แบบอินไลน์:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="background-color: transparent;"/>เพื่อให้การนำเสนอรูปภาพดูเป็นมืออาชีพและสวยงามยิ่งขึ้น คุณสามารถเพิ่มพื้นหลังให้กับรูปภาพได้:
<Background>
</Background>หรือเพิ่มกรอบและคำบรรยายภาพ:
<Frame caption="Appearance Preferences">
</Frame>7. ใช้ตารางเพื่อแสดงข้อมูลที่มีโครงสร้างอย่างชัดเจน
ตารางเป็นวิธีที่ดีที่สุดในการนำเสนอข้อมูลที่มีโครงสร้าง Apidog Markdown รองรับไวยากรณ์ตาราง Markdown มาตรฐานและอนุญาตให้ใช้สไตล์ HTML เพื่อให้ตารางดูเป็นมืออาชีพและสวยงามยิ่งขึ้น
ตารางพื้นฐาน:
| Feature | Status | Description |
| --- | --- | --- |
| User Auth | ✅ Done | Supports multiple login methods |
| Data Sync | ⚠️ In Progress | Expected next week |
| Report Export | ❌ Not Started | Planned for Q3 |ปรับความกว้างของคอลัมน์: ใช้สไตล์ HTML แบบอินไลน์เพื่อควบคุมความกว้างของคอลัมน์และหลีกเลี่ยงเลย์เอาต์ที่ยุ่งเหยิง
| <div style="width: 100px;">Feature</div> | <div style="width: 100px;">Status</div> | <div style="width: 200px;">Descriptions</div> |
| --- | --- | --- |
| User Auth | ✅ Done | Supports multiple login methods |
| Data Sync | ⚠️ In Progress | Expected next week |
| Report Export | ❌ Not Started | Planned for Q3 |
8. ใช้บล็อก Accordion สำหรับ FAQ
บล็อก Accordion เหมาะสำหรับการจัดระเบียบคำถามที่พบบ่อย (FAQs) หรือรายละเอียดที่ไม่จำเป็น โครงสร้างนี้ช่วยให้ผู้อ่านสามารถขยายเนื้อหาได้ตามต้องการ ทำให้หน้าเว็บดูเป็นระเบียบและไม่รกตา
บล็อก Accordion เหมาะอย่างยิ่งสำหรับ FAQs, คุณสมบัติเสริม, การกำหนดค่าขั้นสูง, การแก้ไขปัญหา ฯลฯ ช่วยให้ผู้ใช้เข้าถึงข้อมูลสำคัญได้อย่างรวดเร็วโดยไม่พลาดรายละเอียด
การใช้งานพื้นฐาน:
`<Accordion title="How to reset password?"> 1. Click “Forgot Password” on the login page 2. Enter your registered email address 3. Click “Send Reset Email” 4. Click the reset link in the email and set a new password </Accordion>ตั้งค่าสถานะเริ่มต้น (ยุบ):
<Accordion title="Advanced Settings (Optional)" defaultOpen={false}> This section covers advanced but non-essential options for users with special needs. - Custom request headers - Proxy server settings - Performance optimization </Accordion>
9. ใช้ Notices เพื่อเน้นข้อมูลสำคัญ
Notices และบล็อกไฮไลต์เหมาะสำหรับการเน้นข้อมูลสำคัญ เช่น บันทึก เคล็ดลับ หรือคำเตือน เพื่อให้แน่ใจว่าผู้ใช้จะไม่พลาดเนื้อหาสำคัญ
Notice:
:::tip
This is a tip notice
:::
:::warning
This is a warning notice
:::
:::caution
This is a caution notice
:::
:::danger
This is a danger notice
:::
:::check
This is a check notice
:::
:::info
This is an info notice
:::
:::note
This is a note notice
:::
Highlight block:
:::highlight purple 💡
This is highlighted content
:::
:::highlight yellow 👋
This is highlighted content
:::
:::highlight orange 🚀
This is highlighted content
:::
:::highlight red 🌟
This is highlighted content
:::
:::highlight gray 🚀
This is highlighted content
:::
:::highlight blue 📌
This is highlighted content
:::
:::highlight green 🔑
This is highlighted content
:::
10. เพิ่มคุณสมบัติ Hover และ Copy ให้กับคำศัพท์
ด้วยคอมโพเนนต์ Tooltip คุณสามารถแสดงคำจำกัดความเมื่อวางเมาส์เหนือข้อความได้
<Tooltip tip="This is a tip!"> Hover here for a tip</Tooltip>ด้วยคอมโพเนนต์ CopyToClipboard คุณสามารถคัดลอกข้อความได้ด้วยการคลิก
<CopyToClipboard >Click here to copy text</CopyToClipboard>รวม Tooltip และ CopyToClipboard สำหรับ "hover tip and copy":
<Tooltip tip="This is a tip, and you can copy!"><CopyToClipboard >Click here to copy text</CopyToClipboard></Tooltip>
บทสรุป
ด้วยการใช้คุณสมบัติ Apidog Markdown เหล่านี้อย่างยืดหยุ่น คุณสามารถสร้างเอกสารที่เป็นมืออาชีพและน่าดึงดูดสายตาได้ เอกสารที่ดีช่วยลดต้นทุนการสื่อสาร ปรับปรุงประสิทธิภาพการพัฒนา และแสดงความเป็นมืออาชีพของทีมและคุณภาพของผลิตภัณฑ์ เอกสารที่ยอดเยี่ยมเป็นส่วนสำคัญของประสบการณ์ผลิตภัณฑ์และคุ้มค่ากับการลงทุน สำหรับเคล็ดลับเพิ่มเติม โปรดดู เอกสาร Apidog Markdown