דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- המשאב הלאומי לביולוגיה של הרשת (NRNB)
- כתב טכני:
- Prubhtej_9
- שם הפרויקט:
- יצירת מסמכי תיעוד למשתמשים ל-SynBioHub ופיתוח מדריכים לתרחישי שימוש ספציפיים
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מופשט
תיעוד למשתמש נועד לעזור למשתמשי קצה להשתמש במוצר או בשירות. תיעוד טוב למשתמש חשוב מאוד כי הוא מספק למשתמשים אפשרות ללמוד כיצד להשתמש בתוכנה, בתכונות, בטיפים ובטריקים שלה, וכן לפתור בעיות נפוצות בעת השימוש בתוכנה. בנוסף, הם מפחיתים את עלות התמיכה ומהווה חלק מהזהות הארגונית של המוצר. למשל, תיעוד טוב של המשתמשים הוא סימן למוצר תקין ולצוות המפתחים. ללא תיעוד טוב למשתמש, ייתכן שהמשתמש לא יידע איך לבצע את הפעולות שרשומות למעלה ביעילות וביעילות. מסמכי תיעוד של משתמשים יכולים למלא תפקיד מרכזי בהבטחת ההצלחה של מוצרים, כי תקשורת מעולה היא העיקרון המנחה של כל עסק או מוצר. תיעוד נהדר פשוט לוקח את המסר הזה ומעמיד אותה בתוך מסגרת עבודה שכולם יכולים לגשת אליה כדי להצליח. SinBioHub הוא מאגר לעיצוב לביולוגיה סינתטית. היא זמינה גם כאתר ציבורי וגם כתוכנת קוד פתוח. SinBioHub משתמש ב-Synthetic Biology Open Language (SBOL) תקן קוד פתוח לייצוג עיצובים גנטיים, ומאפשרים גם לשתף חלקי עיצוב מקובצי GenBank ו-FASTA. אפשר להשתמש ב-SynBioHub כדי לפרסם ספרייה של חלקים ועיצובים סינתטיים בתור שירות, לשתף עיצובים עם שותפי עריכה ולאחסן עיצובים של מערכות ביולוגיות באופן מקומי. ניתן לגשת לנתונים ב-SynBioHub דרך HTTP API, Java API או Python API, שם ניתן לשלב אותם בכלי CAD לבניית עיצובים גנטיים. ו-SinBioHub מכיל ממשק שבו משתמשים יכולים להעלות נתונים ביולוגיים חדשים למסד הנתונים, להציג חלקי DNA מסוימים, לבצע שאילתות כדי לגשת לחלקים הרצויים ולהוריד את SBOL, GenBank, FASTA וכו'. מאמרי מחקר שונים ומדריכים מסוימים זמינים גם באינטרנט, כמו למשל: 1. https://pubs.acs.org/doi/bGUI/10acs.102
מצב נוכחי של התיעוד:
כרגע, מסמכי התיעוד למשתמש זמינים בכתובת :“https://syncbiohub.github.io/api-docs/#about-syncbiohub ". אלה רק מסמכי התיעוד בנושא ה-API והתיעוד של ממשק ה-GUI לא קיים, מה שיכול לעזור למשתמש לנווט בתוך מאגר העיצוב. בנוסף, צריך גם לעדכן קצת את מסמכי התיעוד בנושא ה-API, עם כמה נושאים ספציפיים, כמו פתרון בעיות ייחודיות שמשתמשים עשויים להיתקל בהן. הארגון צילם כמה סרטוני הדרכה, כמו הסרטון הזה כאן. אין באמת תיעוד כתוב של המשתמש לגבי SinBioHub, שיכול להנחות את המשתמש.
למה התיעוד המוצע למשתמש הוא שיפור בהשוואה למסמך הנוכחי? אני אבנה את התיעוד של ממשק המשתמש ה-GUI מאפס באמצעות github ו-markdown, לפי הצעת המנטור, מר כריס מאיירס. מסמכי התיעוד שמוצעים למשתמשים ייבנו במטרה לשפר את היעילות, העקביות והשקט הנפשי של כל משתמש קצה. המדריך יכלול מדריכים כתובים והתמונות המשויכות אליו, וגם הוראות והסבר לגבי השימוש בכל אחת מהתכונות של הסימולטור של SinBioHub. במהלך הדיונים עם מר מאיירס , הוחלט גם שמסמכי ה-API ימוזגו עם ממשק ה-GUI ויכילו 6 סעיפים, שמתוכם החלק השישי יהיה אופציונלי. הסעיפים מוזכרים כך: 1. מבוא 2. הוראות התקנה א) מתמונה מוכנה מראש ב) מהמקור ג) הגדרות NGINX 3. הוראות למשתמש א) הוראות מפורטות לשימוש בכל תכונה של ממשק GUI ב) מדריכים לתרחישים נפוצים. 4. תיעוד API - נקודות קצה, סעיף 5. תיעוד הפלאגין 6. פתרון בעיות והפניות עתידיות.
חלק 1:
בחלק הזה יוצג למשתמשים מבוא מפורט ומדריכים שונים לגבי SinBioHub.
חלק 2:
בקטע הזה מוצגות הדרכים השונות שבהן המשתמש יכול להתקין את תוכנת הקוד הפתוח בשיטות שונות, למשל: א) מתמונה מוכנה מראש ב) מהמקור ג) הגדרת NGINX
חלק 3:
זה החלק הכי חשוב בתיעוד, וייקח את רוב הזמן. במסמך זה, כל פרט ודקה יתווספו בהקשר הרלוונטי לממשק ה-GUI. כפי שהוזכר למעלה, נתייחס בעיקר לשני חששות בקטע זה. כלומר, הנחיות מפורטות לשימוש בכל תכונה של ממשק GUI ומספר מדריכים לתרחישים נפוצים.
חלק 4:
כפי שהוזכר קודם, ייעשה שימוש בשקופית חוסמת כדי ליצור את התיעוד של החלק הזה. בקטע הזה ייכללו נקודות הקצה הבאות: 1. נקודות הקצה (endpoints) של המשתמש 2. מחפשים נקודות קצה 3. מורידים Endpoints 4. מורידים נקודת קצה (Endpoints) 5. נקודות קצה להגשה 6. נקודות קצה של הרשאות. 7. עריכת נקודות קצה 8. נקודות קצה (endpoints) של קבצים מצורפים 9. נקודות קצה של ניהול
חלק 5:
בחלק הזה ייכללו תיעוד הפלאגין שכבר קיים בתיעוד הישן של SinBioHub. החלק הזה יחולק לשניים: מפרט והטמעה של יישומי פלאגין. חלק 6: [אופציונלי] הסעיף הזה יכלול רשימה של שגיאות נפוצות מאוד שמשתמשים נתקלים בהן, ויכלול הוראות לפתרון בעיות. בהמשך לדיון עם מר מאיירס, החלטנו שניתן למזג את הקטע הזה עם קטע המבוא, אם קטע הפתיחה לא ארוך מדי. שוחחנו עם מר מאיירס והסברנו איך לעדכן את המסמכים הקיימים וגם איך לכתוב מסמך חדש לממשק ה-GUI. בשיחות ספורות ניסחנו פריסה בסיסית של המסמכים החדשים שצוינו למעלה, וניתנה לוח זמנים משוער בעמוד 5 למטה. בהמשך לדיון, אני אשתמש ב-github ובסימון ממוחשב כדי לבנות את התיעוד לכל קטע, חוץ מחלק 4 של התיעוד שבו ייעשה שימוש בשקופית חוסמת. צפחה:- צפחה עוזרת ליצור תיעוד API יפה, חכם ורספונסיבי. Slate הוא כלי מבוסס-Ruby שיוצר אתר סטטי לתיעוד ממשק API שנראה נהדר בעל שלוש חלוניות, מתוך קבוצת קובצי Markdown. היא נבנתה על ידי המפתח רוברט לורד בשנת 2013, כשעבד בן 18 בחברת תוכנות הנסיעות Triipit. הוא שכנע את הבוס שלו בזמנו לאפשר לו לתת לפרויקט קוד פתוח, והשאר הוא היסטוריה. יש בו את התכונות הבאות: • עיצוב נקי ואינטואיטיבי — באמצעות שקופית חוסמת, התיאור של ה-API מופיע בצד ימין של התיעוד, וכל הדוגמאות של הקוד מופיעות בצד ימין. בהשראת מסמכי ה-API של Stripe ו-PayPal. הצפחה רספונסיבית, כך שהיא נראית מצוין בטאבלטים, בטלפונים ואפילו בהדפסה. • הכול בדף אחד – חלפו הימים שבהם המשתמשים היו צריכים לחפש במיליון דפים כדי למצוא את מה שהם מחפשים. Slate מציב את כל התיעוד בדף אחד. עם זאת, לא הפשרנו על אפשרות הקישור. כשתגללו, הגיבוב של הדפדפן יתעדכן לכותרת הקרובה ביותר, כך שקישור לנקודה מסוימת בתיעוד הוא עדיין טבעי וקל. • Slate הוא פשוט Markdown — כשכותבים מסמכים באמצעות Slate, פשוט כותבים Markdown, וכך קל לערוך ולהבין אותם. הכול כתוב ב-Markdown — אפילו דוגמאות הקוד הן רק בלוקים של קוד Markdown. • כתיבת דוגמאות קוד במספר שפות — אם ה-API שלכם כולל קישורים בשפות תכנות מרובות, תוכלו להוסיף בקלות כרטיסיות שונות כדי לעבור ביניהן. במסמך, אפשר להבחין בין שפות שונות על ידי ציון שם השפה בחלק העליון של כל בלוק קוד, בדיוק כמו ב-GitHub Flavored Markdown. • הדגשת תחביר ייחודי עבור יותר מ-100 שפות, ללא צורך בהגדרה נוספת. • גלילה אוטומטית וחלקה של תוכן העניינים בקצה השמאלי של הדף. תוך כדי גלילה, הוא מציג את המיקום הנוכחי שלכם במסמך. הוא גם מהיר. אנחנו משתמשים ב-Slate ב-TripIt כדי ליצור תיעוד עבור ה-API החדש שלנו, שכולל יותר מ-180 רשומות. וידאנו שהביצועים יישארו מצוינים, גם עבור מסמכים גדולים יותר. • המשתמשים יכולים לעדכן את המסמכים עבורך — כברירת מחדל, התיעוד שנוצר על ידי Slate מתארח במאגר ציבורי של GitHub. המשמעות היא שמארחים בחינם של המסמכים שלך ב-GitHub Pages, אלא גם יקל על מפתחים אחרים לשלוח בקשות משיכה למסמכים שלך אם הם יגלו שגיאות הקלדה או בעיות אחרות. כמובן, אם אינך רוצה להשתמש ב-GitHub, אתה גם מוזמן לארח את המסמכים שלך במקומות אחרים. • תמיכה מימין לשמאל בכל שפה מימין לשמאל עבור שפות RTL כמו ערבית, פרסית (פרסית), עברית ועוד. Verdict Slate היא אחת מתוכנות הקוד הפתוח העוצמתיות ביותר ליצירת התיעוד, ולפי הדיונים עם המנטור שלי, מר כריס מאיירס, השתמשתי ב-Slate בחלק 4 ובחלקים אחרים, ייעשה שימוש ב-github וב-Markdown. בקטעים הבאים יש סקירה מפורטת יותר של התיעוד. מבנה עבור המסמכים שהצעתי. יצרתי מבנה למדריך למשתמש של SinBioHub, שמופיע בעמוד 2. מבנה זה התקבל וכבר שונה על ידי מר מאיירס . יעדי הפרויקט 1. משנים את מבנה המסמכים. 2. כדאי לעדכן את המסמכים כך שיתאימו לגרסאות המודרניות של SinBioHub. 3. הסרת מידע מיושן. 4. לנסח מחדש את תיעוד המשתמש כדי שיהיה קל יותר להבין אותו. 5. יש להוסיף למסמכי התיעוד של השותפים החדשים סעיף קצר שבו יש לעמוד בדרישות מוקדמות, כדי להעמיק את ההבנה הבסיסית שלהם במושגים ביולוגיים בסיסיים ובממשק של SinBioHub.