פרויקט Creative Commons

בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.

סיכום הפרויקט

ארגון קוד פתוח:

Creative Commons

כותבים טכניים:

nimishnb

שם הפרויקט:

מדריך לשימוש במילון

אורך הפרויקט:

אורך סטנדרטי (3 חודשים)

תיאור הפרויקט

תקציר הפרויקט

ל-Vocabulary יש פוטנציאל עצום לשימוש כספרייה ראשית של רכיבי ממשק משתמש לצורך בניית אתרים. מה שדרוש הוא מדריך מקיף ועדיין ידידותי לאנשים רגילים. מידע חשוב למפתחים, כמו מדריכים לרכיבים, מפרטים של שימוש ושינוי הגדרות, מהווה חלק חיוני בכל תיעוד. כך המשתמשים הקיימים יוכלו להבין איך אוצר המילים ממשיך להתפתח ולהגיע לאבני דרך חדשות, אלא גם יעודד את השימוש באוצר המילים בפרויקטים חדשים יחסית. התוצאות הרצויות של תקופת ההתמחות שלי יהיו לא רק כתיבת מדריך פשוט לשימוש ברכיבים הקיימים, אלא גם עיצוב ופיתוח של דף בית (שיובילו למסמכי תיעוד משולבים לכל אחד מהם) עבור Vocabulary,‏ Vue-Vocabulary ו-Fonts.

תוכנית הפרויקט

1. הבעיה: אחד מהגורמים העיקריים שקובע את מידת ההצלחה של ספרייה מסוימת בקוד פתוח הוא התיעוד שלה. השאלה העיקרית שמפתחים שואלים את עצמם כשהם בוחרים סטאק טכנולוגי מתאים ליצירת האפליקציות שלהם היא "האם יש לספרייה תיעוד טוב? האם הוא מתוחזק היטב? האם יש לו תמיכה משמעותית בשימוש ובשגיאות?". אלה בדיוק השאלות שאנחנו צריכים לשאול את עצמנו כשאנחנו מפתחים את הרעיון של הפרויקט. מנקודת מבט של הנדסת תוכנה:

2. ניתוח דרישות: קיים צורך מיידי במסמכי תיעוד תמציתיים ומאוחדים שמתאימים לצרכים שלנו. חוסר התיעוד פוגע בתחזיות העתידיות של אפליקציות בקוד פתוח, והוא ללא ספק רכיב חיוני ולא זניח. הקישור למסמכים האלה צריך להיות דף בית מושך ומעורר עניין בקרב האנשים באופן מיידי. חשוב שהמסמכים יהיו מאורגנים היטב, כדי שאפשר יהיה לעבור ביניהם בצורה חלקה.

3. מפרטים: בהתאם לדרישות, אפשר להחליט על המפרטים. תוכלו ליצור את התוכן במסמכי העזרה מנתונים שקיימים באתרי CC netlify, יחד עם השראה ממסמכי עזרה ידועים כמו semantic-ui, ‏ scikit-learn, ‏ numpy, ‏ bootstrap וכו'. התוצר של המשימה הזו יהיה דף הנחיתה הנדרש ומדריכי העזרה המלאים.

יש כמה בעיות כלליות שקשורות כרגע ל-Vocabulary, ל-Vue-Vocabulary ולגופנים:

• אין מסמכי עזרה, ואפילו אם יש, חלקים מהם מפוזרים באתרים השונים של Netlify. המהלך הזה לא מונע ממשתמשים, ממפתחים או מתורמים חיצוניים להשתמש בספרייה שלנו.

  • כדי להגיע לרכיב מסוים ולהעתיק את הקוד התואם שלו נדרשים קליקים נוספים. חיפוש פשוט ב-Google של 'רכיב הכרטיסיות CC Vocabulary' לא מחזיר את המידע הרצוי. אפשרות חיפוש במדריכי התיעוד תשפר משמעותית את חוויית המשתמש.

  • תיאור מפורט יותר של הרכיבים, שמתאר את הפרטים הלא ברורים.

  • אין אפשרות להרצה בזמן אמת. הרצה פעילה נתמכת על ידי אתרים שונים כמו JSFiddle, וכך מפתחים יכולים להכיר את הרכיב בלי להפעיל אפליקציה שלמה כדי לראות אותו פועל.

הפתרון

יש כמה פתרונות אפשריים. עם זאת, אציג כאן כמה מהן ואציג את הפתרון הסופי שלי בסיום המאמר:-

‎= Using readthedocs readthedocs הוא פתרון ידוע לכתיבת מסמכי עזרה לספריות בקוד פתוח. הוא מבוסס על Sphinx, כלי התיעוד של Python.

יתרונות:

1. שיטה מקובלת ליצירת מסמכים משמשת ארגונים כמו Ethereum (Solidity).
2. תיעוד מובנה בצורה אופטימלית.
3. אירוח סטטי בחינם.

חסרונות:

1. אין שליטה מלאה על העיצוב.

= שימוש ב-Sphinx אפשר להשתמש ב-Sphinx גם בחלק של התיעוד, כי יש לו תכונות טובות לכל המטרות שלנו.

יתרונות:

1. הכלי הפופולרי ביותר ב-Python ליצירת מסמכי עזר.
2. יש תמיכה גם בחיפושים של מסמכי עזרה.
3. אפשר לשנות את קובץ ה-CSS שמוגדר כברירת מחדל באמצעות קובץ מותאם אישית. יש גם שליטה מסוימת על קובצי ה-HTML באמצעות קובצי ‎.rst.

חסרונות:

1. תהיה צורך לכתוב קוד ב-Python ובפורמט טקסט מובנה מחדש (‎.rst), שיהיה שונה מהשפות המוצעות לפרויקט.

= שימוש בעיצובי Jekyll עיצובי Jekyll משולבים בדפי github, ויש תבניות קיימות מראש שאפשר להתאים אישית בהתאם לצרכים שלנו.

יתרונות:

1. נושאי תיעוד מוכנים לכל מטרה.
2. ניתן לבטל סגנונות ו-CSS שמוגדרים כברירת מחדל בסגנונות מותאמים אישית, ולנהל גם על HTML.
3. שולפת את שירות ה-CSS המוגדר כברירת מחדל של Primer כדי לבנות את הדפים.
4. שילוב קל עם GitHub Pages.

חסרונות:

1. יכול להיות שהמבנה של המסמכים לא יהיה הכי טוב.

=שימוש ב-GitHub Pages דפי GitHub רגילים ליצירת האתר הסטטי שלנו (HTML, ‏ CSS, ‏ JS).

יתרונות:

1. שליטה מלאה כמעט על כל מה המדובר.
2. גמישות מקסימלית בבחירת הפריסה, הצבעים והסגנונות.
3. שימוש קל ברכיבי Vocabulary.
4. הטמעה קלה של קטעי קוד וקישורים להרצה בזמן אמת.

חסרונות:

1. יכול להיות שזו גישה שדורשת יותר זמן.

= שימוש ב-Haroopad במקום זאת, הפתרון החלופי הוא markdown.

יתרונות:

1. דורשת מינימום קוד מסובך.
2. המיקוד יהיה על כתיבת המסמכים בצורה מושלמת.

חסרונות:

1. חוסר שליטה בשירות ה-CSS.
2. יכול להיות שתקבלו תמיכה טובה מהקהילה, ויכול להיות שלא.
3. יכול להיות שאין תמיכה ב-MDX.

‎= Using MKDocs ‎במקום זאת, זה נותן פתרון חלופי אחר של markdown.

יתרונות:

1. התוכן עשוי לכלול קידוד סודי מינימלי (שוב).
2. גישה של 'כותבים יותר, כותבים פחות קוד'.

חסרונות:

1. חוסר שליטה ב-CSS.
2. יכול להיות שלא תקבלו את התמיכה הטובה ביותר מהקהילה.
3. הקוד מבוסס על Python, ויכול להיות שתצטרכו להפעיל מכונה של Amazon S3.

= שימוש ב-VueJS +StorybookJS הגישה הזו נפוצה ב-Vocabulary ובמאגרים הקשורים אליו.

יתרונות:

1. אנחנו משתמשים בטכנולוגיות שמובטחות שהן יעבדו כמו שצריך, על סמך ניסיון העבודה הקודם שלכם.
2. היכרות עם קוד הבסיס.
3. אין טכנולוגיה מתאימה בתחום הזה.

חסרונות:

1. יכול להיות שיהיו גם אפשרויות פשוטות יותר לאותה מטרה.

לסיכום, נראה לי שהגישה שכוללת את VueJS+Storybook (HTML,‏ CSS,‏ JS) היא הגישה המתאימה ביותר, מכיוון שהיא גם מתאימה לי. עם זאת, המשמעות היא גם שלא נשקיע מאמצים רבים בפיתוח האפליקציה הזו. בנוסף, קל יחסית להשתמש ברכיבי CC-Vocabulary. עם זאת, כדי לקבוע את מבנה התיעוד, צריך בהחלט לשקול את אופן חלוקת התוכן בין כותרות המשנה במסמכי Readthedocs. התרשמנוי מהאתר הסמנטי בממשק המשתמש (שמשתמש ב-StoryBook) כי יש לו מראה מינימליסטי, ואפשר להבין בקלות מה הם רוצים לדעת אחרי כמה לחיצות. חוץ מממשק המשתמש הסמנטי, בדקתי גם את העיצוב Material Design, Primer, Batstrap, Carbon Design וכו', שישמש כמדריכי עיצוב לממשקי ומערכות עיצוב לעבודה שלי. אפשר גם לחפש נושאים מוכנים למסמכי עזרה של Jekyll כדי לקבל השראה.