בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- OpenMRS.org
- כותבים טכניים:
- batbrain7
- שם הפרויקט:
- מסמכי התיעוד של OpenMRS API ל-REST
- אורך הפרויקט:
- אורך רגיל (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, את סוגי ה-JSON או כל סוג אחר של תוצאה שמוחזרת על ידי ממשקי ה-API.
המסלולים השונים של ה-API ואילו פרמטרים צריך לשלוח יחד איתם, הכותרות ודברים אחרים. לכל ממשק API יתווספו דוגמאות קוד בכמה שפות שמתארות איך שולחים את הבקשה בזמן כתיבת הקוד שלה. בנוסף, צריך לציין גם קודי שגיאה כלליים שעשויים להופיע בכל ממשק API.
זוהי סקירה כללית של אופן ההגדרה של המסמכים ל-API ל-REST.
לוח הזמנים של הפרויקט הוא :
1 באוגוסט עד 1 בספטמבר
נכיר את המנטור שלי ונדבר לעומק על רמת התיעוד הנדרשת בחלקים שונים של קוד המקור, וגם על מידת הפירוט הנדרשת בתיעוד ברמה נמוכה לעומת ברמה גבוהה. בנוסף, אשתמש בזמן הזה כדי להבין את קוד המקור ולחקור את המושגים, כדי שאוכל לתעד אותם בצורה טובה יותר.
שבוע 1 ו-2
אעדכן וארחיב את המדריך לתורמי תוכן. אשתפר את המסמכים בנושא פיתוח קוד המקור. אוסיף גם קטע בנושא תיעוד, שבו אסביר איך שותפים חדשים יכולים לעזור בתיעוד. אעיין במסמכי העזרה השונים של ה-API, אתחיל מהמבוא ואוסיף את האימות ל-API.
שבוע 3 עד 8
אני אוסיף את הנתיבים והתשובות של ה-API יחד עם כמה דוגמאות קוד לכל סוג של API (יכולים להיות סוגים דומים של ממשקי API).
שבוע 9 ו-10
מוסיפים את המבנה של מסמכי התיעוד של ה-API באמצעות קישורים, כלומר, מדד מקושר למסמכי תיעוד ארוכים של API, ומחלקים אותו עוד יותר על בסיס שונה, כמו קטעי קוד, סקירה כללית, פרמטרים, נקודות קצה ברמה הבסיסית.
השבוע האחרון
אשתמש בשבוע האחרון כדי להכין את הדוח הסופי על העבודה שבוצעה במהלך תקופת התיעוד של 12 השבועות. בנוסף, אקדיש את הזמן הזה לבדיקת המסמכים ולסיום שלהם.