דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- OpenMRS.org
- כתב טכני:
- batbrain7
- שם הפרויקט:
- מסמכי תיעוד של OpenMRS REST API
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
אחלק את ההצעה שלי לחלקים שונים ואעקוב אחר התהליך, כמו תיעוד של ממשק ה-API של מפות Google והתיעוד של GitHub API.
מלבד זאת, אני רוצה להציע מבנה Readme לתיעוד ה-API שמבוצע על ידי Realworld.io: https://github.com/gothinkster/realworld/tree/master/api
באופן אישי, מצאתי שתיעוד זה קל להבנה ולשימוש.
ההצעה שלי תכלול בעיקר 3 חלקים :
קטע שמספק מבוא קצר על ממשק ה-API, על OpenMRS ועל אופן השימוש בו ועל מה שקורה אחריו.
איך מקבלים את מפתח ה-API ומה האימות הנדרש באופן כללי כדי לשלוח את בקשת ה-API. בקטע הזה תהיה דוגמה לסוגי האימות שקיימים ב-API, למפתחות ולערכים שצריך להיות קיימים, וגם סוגי הערכים הקבילים שתואמים למפתח שבאותו חלק. דוגמת קוד בכל שפה תעזור ומבהירה איך לכתוב את הכותרות והפורמטים של התגובות ופרמטרים אחרים של שאילתות ב-API.
יצוינו סוגי התגובות שאוחזרו על ידי ה-API, סוגי ה-JSON או כל סוג אחר של תוצאה שמוחזרת על ידי ממשקי ה-API.
נתיבי ה-API השונים והפרמטרים שיש לשלוח יחד עם אלה, הכותרות ודברים נוספים. כל ממשק API יקבל סיוע באמצעות דגימות קוד בכמה שפות שמתארות את אופן ביצוע הבקשה במהלך כתיבת הקוד עבורו, פרט לקודי השגיאה הכלליים שעשויים להופיע בכל ממשק API.
זה מושג כללי לגבי האופן שבו התיעוד יוגדר ל-API ל-REST.
לוח הזמנים לפרויקט הוא כדלקמן :
1 באוגוסט – 1 בספטמבר
לערוך היכרות עם המנטור שלי ולדון לעומק ברמת התיעוד הנדרשת בחלקים שונים של ה-codebase, וגם לדון באופן מעמיק בתיעוד ברמה נמוכה לעומת תיעוד ברמה גבוהה. גם אקדיש את הזמן הזה כדי להבין את בסיס הקוד וללמוד את המושגים כדי שאוכל לתעד אותם טוב יותר.
שבוע 1 ו-2
אני אעדכן וארחיב את המדריך ליוצרים. אני אשפר את התיעוד לגבי אופן הבנייה של קוד המקור. אני אוסיף גם את הקטע של מפרסמים שעוסקים בתיעוד, שבו מוסבר איך תורמי תוכן חדשים יכולים לעזור בתיעוד. אלמד את מסמכי התיעוד השונים של ממשק ה-API, אתחיל במבוא ואוסיף את האימות ל-API.
שבוע 3 עד 8
אני אוסיף את הנתיבים והתגובות של ה-API וגם כמה דוגמאות קוד לכל סוג של API (ייתכן שיהיו סוגים דומים של ממשקי API).
שבוע 9 ו-10
צריך להוסיף את המבנה של תיעוד ה-API באמצעות קישורים, כלומר אינדקס מקושר למסמכי API ארוכים ולחלק אותם על בסיס שונה, למשל קטעי קוד, סקירה כללית, פרמטרים ונקודות קצה (endpoint) ברמה הבסיסית.
השבוע האחרון
בשבוע האחרון אכין את הדוח הסופי שלי לגבי העבודה שהכנתי במהלך 12 השבועות לתיעוד. בינתיים אקדיש את הזמן הזה כדי לבדוק את המסמכים ולהשלים אותם.