בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- National Resource for Network Biology (NRNB)
- כותבים טכניים:
- Prubhtej_9
- שם הפרויקט:
- יצירת מסמכי עזרה למשתמש ב-SynBioHub ופיתוח מדריכים למקרים ספציפיים של שימוש
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
מופשט
מסמכי תיעוד למשתמש נועדו לסייע למשתמשי הקצה להשתמש במוצר או בשירות. תיעוד משתמש טוב הוא חשוב מאוד כי הוא מספק למשתמשים דרך ללמוד איך להשתמש בתוכנה, להכיר את התכונות שלה, לקבל טיפים וטריקים ולפתור בעיות נפוצות שנתקלים בהן בזמן השימוש בתוכנה. הוא גם מפחית את עלות התמיכה והוא חלק מהזהות הארגונית של המוצר. כלומר, תיעוד טוב של המשתמש הוא סימן למוצר תקין ולצוות הפיתוח. בלי מסמכי עזרה טובים למשתמש, יכול להיות שהמשתמש לא ידע איך לבצע את הפעולות שצוינו למעלה בצורה יעילה ואפקטיבית. מסמכי עזרה למשתמשים יכולים למלא תפקיד מרכזי בהבטחת ההצלחה של מוצר, כי תקשורת טובה תמיד תהיה בלב ליבה של כל עסק או מוצר, ומסמכי עזרה טובים פשוט מעבירים את התקשורת הזו למסגרת ניהולית שכל אחד יכול לגשת אליה כדי להצליח. SynBioHub הוא מאגר עיצוב לביולוגיה סינתטית. הוא זמין גם כאתר ציבורי וגם כתוכנת קוד פתוח. ב-SynBioHub נעשה שימוש בשפה הפתוחה של ביולוגיה סינתטית (SBOL), תקן בקוד פתוח לייצוג עיצובים גנטיים. בנוסף, המערכת מאפשרת לשתף חלקים של עיצובים מקובצי GenBank ו-FASTA. אפשר להשתמש ב-SynBioHub כדי לפרסם ספרייה של חלקים ועיצובים סינתטיים כשירות, לשתף עיצובים עם שותפי עריכה ולאחסן עיצובים של מערכות ביולוגיות באופן מקומי. ניתן לגשת לנתונים ב-SynBioHub דרך API ל-HTTP, Java API או Python API, ולאחר מכן לשלב אותם בכלי CAD לפיתוח עיצובים גנטיים. SynBioHub מכיל ממשק שמאפשר למשתמשים להעלות נתונים ביולוגיים חדשים למסד הנתונים, להציג חלקי DNA באופן חזותי, לבצע שאילתות כדי לגשת לחלקים הרצויים ולהוריד SBOL, GenBank, FASTA וכו'. באינטרנט זמינים גם מאמרים שונים של מחקרים ומדריכים מסוימים, למשל: 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 ב-SynBioHub יש קצת מסמכי עזרה שקשורים רק ל-API, אבל אין מסמכי עזרה לגבי ממשק המשתמש הגרפי.
המצב הנוכחי של התיעוד:
בשלב זה, מסמכי העזרה למשתמשים זמינים בכתובת: https://synbiohub.github.io/api-docs/#about-synbiohub. זהו רק מסמך העזרה של ה-API, ומסמך העזרה של ממשק המשתמש לא קיים, ולכן לא ניתן לעזור למשתמש לנווט במאגר התכנון. בנוסף, התיעוד של ה-API דורש קצת עדכון בנושאים ספציפיים, כמו פתרון בעיות של בעיות ייחודיות מסוימות שהמשתמשים עשויים להיתקל בהן. הארגון כן צילם כמה סרטוני הדרכה, כמו הסרטון הזה. אין ממש מסמכי עזרה בכתב למשתמש בנושא SynBioHub שיכולים להנחות את המשתמש.
למה המסמך המוצג שלך הוא שיפור על פני המסמך הנוכחי? אני אבנה את תיעוד ה-GUI מאפס באמצעות github ו-Markdown כפי שהוצע על ידי המנטור, מר כריס מאיירס. מסמכי התיעוד המוצעים למשתמשים יותאמו כך שישפרו את היעילות, העקביות והשקט הנפשי של כל משתמש קצה. הוא יכלול מדריכים כתובים ותמונות משויכות, וגם הוראות והסברים על אופן השימוש בכל תכונה של הסימולטור הפתוח SynBioHub. במהלך הדיונים עם מר Myers, הוחלט גם שמסמכי התיעוד של ה-API ימוזגו עם ממשק המשתמש ויכללו 6 קטעים, כאשר הקטע השישי יהיה אופציונלי. הקטעים מופיעים כך: 1. מבוא 2. הוראות התקנה א) מתוך קובץ אימג' שנוצר מראש ב) ממקור ג) הגדרת NGINX 3. הוראות למשתמשים: א) הוראות מפורטות לשימוש בכל תכונה של ממשק המשתמש. ב) מדריכים לתרחישי שימוש נפוצים. 4. תיעוד API – קטע 5 בנושא נקודות קצה. תיעוד הפלאגין 6. פתרון בעיות ומידע לשימוש עתידי.
חלק 1:
בקטע הזה, המשתמשים יקבלו מבוא מפורט ומדריכים שונים בנוגע ל-SynBioHub.
חלק 2:
בקטע הזה מפורטות הדרכים השונות שבהן המשתמש יכול להתקין את תוכנת הקוד הפתוח באמצעות שיטות שונות, כלומר: א) מתוך קובץ אימג' שנוצר מראש ב) מהמקור ג) הגדרת NGINX
חלק 3:
זהו החלק הקריטי ביותר במסמכים והוא יכסה את רוב הזמן. כאן כל פרט קטן יתווסף לממשק המשתמש בהקשר שלו. כפי שצוין למעלה, בקטע הזה נעסוק בעיקר בשני נושאים: הוראות מפורטות לשימוש בכל תכונה של ממשק המשתמש, ומדריכים מסוימים לתרחישי שימוש נפוצים.
חלק 4:
כפי שציינו למעלה, יצירת התיעוד של החלק הזה תתבצע באמצעות צפחה. בקטע הזה ייכללו נקודות הקצה הבאות: 1. נקודות קצה של משתמשים 2. חיפוש נקודות קצה 3. מורידים את Endpoints 4. מורידים את Endpoints 5. נקודות קצה לשליחה 6. נקודות קצה להרשאות. 7. עריכת נקודות הקצה 8. נקודות קצה של קבצים מצורפים 9. נקודות קצה לניהול
חלק 5:
בקטע הזה ייכלל מסמך העזרה של הפלאגין שכבר קיים במסמכי העזרה הישנים של SynBioHub. הקטע הזה יתחלק לשני חלקים: מפרט הפלאגין והטמעה שלו. חלק 6: [אופציונלי] הקטע הזה יכלול רשימה של שגיאות נפוצות מאוד שמשתמשים נתקלים בהן, וגם כמה הוראות לפתרון בעיות. בהמשך לשיחה עם המורה מאיירס, הוחלט שאפשר למזג את הקטע הזה עם קטע המבוא, בתנאי שהתהליך לא ארוך מדי. ניתוח היו לי שיחות עם מר Myers לגבי האופן שבו לעדכן את המסמכים הקיימים וגם לכתוב מסמך חדש לממשק המשתמש. בשיחות האלה הגדרנו פריסה בסיסית למסמכים החדשים שצוינו למעלה, וציר הזמן המשוער מופיע בדף 5 בהמשך. בהתאם לדיון, אני אשתמש ב-github וב-Markdown כדי לבנות את התיעוד עבור כל קטע, מלבד חלק 4 של התיעוד שבו ייעשה שימוש בSlate. Slate:- Slate עוזר ליצור תיעוד יפה, חכם ורספונסיבי של ממשקי API. Slate הוא כלי מבוסס-Ruby שיוצר אתר סטטי עם מסמכי עזרה של API בשלוש חלוניות, שנראה מצוין, מקבוצה של קובצי markdown. הוא הוקם על ידי המפתח רוברט לורד ב-2013 כשהיה מתמחה בן 18 בחברת תוכנת הנסיעות Triipit. הוא שכנע את הבוס שלו באותו זמן לאפשר לו לפרסם את הפרויקט בקוד פתוח, והשאר הוא היסטוריה. התכונות הבאות זמינות ב-Slate: • עיצוב נקי ואינטואיטיבי – ב-Slate, התיאור של ה-API מופיע בצד ימין של המסמך, וכל דוגמאות הקוד מופיעות בצד ימין. המסמכים האלה התבססו על מסמכי ה-API של Stripe ו-PayPal. הגופן Slate הוא רספונסיבי, כך שהוא נראה מצוין בטאבלטים, בטלפונים ואפילו בפורמט מודפס. • הכל בדף אחד – עברו הימים שבהם המשתמשים שלכם היו צריכים לחפש מיליון דפים כדי למצוא את מה שהם חיפשו. מערכת Slate משלבת את כל המסמכים בדף אחד. עם זאת, לא ויתרנו על האפשרות לקשר את התמונות. כשגוללים, ה-hash של הדפדפן מתעדכן לכותרת הקרובה ביותר, כך שעדיין קל וטבעי לקשר לנקודה מסוימת במסמכי העזרה. • Slate הוא רק Markdown – כשכותבים מסמכים ב-Slate, כותבים רק Markdown, כך שקל לערוך ולהבין אותם. הכל נכתב ב-Markdown – אפילו דוגמאות הקוד הן רק בלוקים של קוד Markdown. • כתיבת דוגמאות קוד בכמה שפות – אם ל-API יש קישורים בכמה שפות תכנות, אפשר להוסיף כרטיסיות בקלות כדי לעבור ביניהם. כדי להבדיל בין שפות שונות במסמך, מציינים את שם השפה בחלק העליון של כל בלוק קוד, בדיוק כמו ב-GitHub Flavored Markdown. • הדגשת תחביר מובנית ביותר מ-100 שפות, ללא צורך בהגדרה. • תוכן עניינים אוטומטי שגלול בו בצורה חלקה, בפינה הימנית הרחוקה של הדף. כשמעבירים את הסמן, מופיע המיקום הנוכחי במסמך. זה גם מהיר. אנחנו משתמשים ב-Slate ב-TripIt כדי ליצור מסמכי עזרה ל-API החדש שלנו, וטבלת התוכן שלנו כוללת יותר מ-180 רשומות. הקפדנו שהביצועים יישארו מעולים גם במסמכים גדולים יותר. • לאפשר למשתמשים לעדכן את המסמכים במקומכם – כברירת מחדל, התיעוד שנוצר באמצעות Slate מתארח במאגר ציבורי של GitHub. זה אומר שאתם מקבלים אירוח בחינם עבור המסמכים שלכם עם דפי GitHub, אלא גם מאפשרים למפתחים אחרים לשלוח בקשות משיכה למסמכים שלכם בקלות אם הם מגלים שגיאות הקלדה או בעיות אחרות. כמובן, אם אתם לא רוצים להשתמש ב-GitHub, אתם יכולים לארח את המסמכים שלכם גם במקום אחר. • תמיכה בצד ימין של המסך בשפות RTL, כגון ערבית, פרסית (פרזית), עברית וכו'. Verdict Slate היא אחת מתוכנות הקוד הפתוח העוצמתיות ביותר ליצירת התיעוד, ובהתאם לדיונים עם החונך שלי, מר כריס מאיירס, אני אשתמש בצפחה בחלק 4 ובחלקים אחרים, ייעשה שימוש ב-github. סקירה מפורטת יותר של התיעוד מופיעה בקטעים הבאים. מבנה למסמכי העזרה המוצעים. יצרתי מבנה למדריך למשתמש של SynBioHub, שזמין בדף 2. המבנה הזה מקובל וכבר שונה על ידי מר Myers. יעדי הפרויקט 1. שינוי המבנה של המסמכים. 2. מעדכנים את התיעוד כך שיתאים לגרסאות המודרניות של SynBioHub. 3. מסירים מידע לא רלוונטי. 4. משכתבים את מסמכי התיעוד למשתמש כדי שיהיה קל יותר להבין אותם. 5. מומלץ לכלול בקטע 'דרישות מוקדמות' בתיעוד שלכם מידע שיסייע לתורמים חדשים להבין את המושגים הבסיסיים בביולוגיה ואת הממשק של SynBioHub.