หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- OpenMRS.org
- นักเขียนเชิงเทคนิค:
- batbrain7
- ชื่อโปรเจ็กต์:
- เอกสารประกอบเกี่ยวกับ OpenMRS REST API
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
เราจะแบ่งข้อเสนอออกเป็นส่วนๆ และจะเป็นไปตามขั้นตอนต่างๆ เช่น เอกสารประกอบของ Google Maps API และเอกสารประกอบของ Github API
นอกจากสิ่งเหล่านี้แล้ว เรายังขอเสนอโครงสร้าง readme สำหรับเอกสารประกอบ API ที่จัดทำโดย realworld.io อีกด้วย https://github.com/gothinkster/realworld/tree/master/api
เราพบว่าเอกสารประกอบนี้เข้าใจและใช้งานได้ง่ายมาก
ข้อเสนอของฉันจะแบ่งออกเป็น 3 ส่วนหลักๆ ดังนี้
ส่วนที่จะแนะนำข้อมูลคร่าวๆ เกี่ยวกับ API, OpenMRS และวิธีใช้ API รวมถึงสิ่งที่จะเกิดขึ้นหลังจากนั้น
วิธีรับคีย์ API และการตรวจสอบสิทธิ์ที่จำเป็นโดยทั่วไปเพื่อสร้างคำขอ API ข้อมูลนี้ประกอบด้วยตัวอย่างประเภทการตรวจสอบสิทธิ์ที่มีอยู่ใน API และคีย์และค่าที่จำเป็นต้องมีสำหรับ API และประเภทค่าที่ยอมรับซึ่งสอดคล้องกับคีย์ในส่วนนั้นๆ ตัวอย่างโค้ดในภาษาใดก็ได้จะช่วยอธิบายวิธีเขียนส่วนหัวและรูปแบบการตอบกลับ รวมถึงพารามิเตอร์การค้นหาอื่นๆ ใน API
โปรดระบุประเภทของคำตอบที่ API ดึงข้อมูล ประเภท JSON หรือผลการค้นหาประเภทอื่นๆ ที่ API แสดง
เส้นทาง API ต่างๆ และพารามิเตอร์ทั้งหมดที่ต้องส่งไปพร้อมกับเส้นทางเหล่านั้น ส่วนหัว และอื่นๆ API แต่ละรายการจะมีตัวอย่างโค้ดในภาษาต่างๆ 2-3 ภาษาที่อธิบายวิธีส่งคําขอขณะเขียนโค้ดสําหรับ API นั้นๆ นอกเหนือจากนี้ ควรระบุรหัสข้อผิดพลาดทั่วไปที่อาจพบได้กับ API แต่ละรายการด้วย
นี่เป็นภาพรวมทั่วไปของวิธีกำหนดเอกสารประกอบสำหรับ REST API
กำหนดการสำหรับโปรเจ็กต์มีดังนี้
1 สิงหาคม - 1 กันยายน
ทำความรู้จักกับที่ปรึกษาและพูดคุยอย่างละเอียดยิ่งขึ้นเกี่ยวกับระดับของเอกสารประกอบที่จําเป็นในส่วนต่างๆ ของโค้ดเบส รวมถึงพูดคุยเกี่ยวกับระดับความละเอียดของเอกสารประกอบระดับล่างกับระดับสูง นอกจากนี้ ฉันยังจะใช้เวลาทำความเข้าใจฐานของโค้ดและศึกษาแนวคิดเพื่อให้บันทึกได้ดียิ่งขึ้น
สัปดาห์ที่ 1 และ 2
เราจะอัปเดตและขยายคู่มือสำหรับผู้มีส่วนร่วม เราจะปรับปรุงเอกสารประกอบเกี่ยวกับวิธีสร้างซอร์สโค้ด นอกจากนี้ เราจะเพิ่มส่วนผู้เขียนเอกสารเกี่ยวกับวิธีที่ผู้มีส่วนร่วมใหม่สามารถช่วยเขียนเอกสารประกอบ เราจะศึกษาเอกสารประกอบของ API ต่างๆ และเริ่มต้นด้วยข้อมูลเบื้องต้นและเพิ่มการตรวจสอบสิทธิ์สําหรับ API
สัปดาห์ที่ 3 - 8
เราจะเพิ่มเส้นทางและคำตอบของ API พร้อมกับตัวอย่างโค้ดบางส่วนสำหรับ API แต่ละประเภท (อาจมี API ประเภทที่คล้ายกัน)
สัปดาห์ที่ 9 และ 10
เพิ่มการจัดโครงสร้างเอกสารประกอบ API โดยใช้ลิงก์ เช่น ดัชนีที่ลิงก์สำหรับเอกสารประกอบ API แบบยาว และแบ่งออกเป็นส่วนๆ ตามเกณฑ์ต่างๆ เช่น ส่วนโค้ด ภาพรวม พารามิเตอร์ ปลายทางรูท
สัปดาห์สุดท้าย
ฉันจะใช้สัปดาห์สุดท้ายในการเตรียมรายงานฉบับสุดท้ายสำหรับงานที่ทำในช่วง 12 สัปดาห์ในเอกสาร เราจะใช้เวลานี้เพื่อตรวจสอบและสรุปเอกสารประกอบให้เสร็จสมบูรณ์ด้วย