פרויקט Creative Commons

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

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

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

Creative Commons

כתב טכני:

nimishnb

שם הפרויקט:

מדריך לשימוש באוצר מילים

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

אורך רגיל (3 חודשים)

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

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

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

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

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

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

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

כרגע יש כמה בעיות כלליות הקשורות לאוצר המילים, Vue-Vocabulary ו-Fonts:

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

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

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

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

הפתרון

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

= השימוש ב-readthedocs ל-readthedocs הוא פתרון מוכר היטב לכתיבת מסמכים עבור ספריות קוד פתוח. היא מבוססת על ספינקס, כלי התיעוד של python.

יתרונות:

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

חסרונות:

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

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

יתרונות:

1. כלי ה-python הפופולרי ביותר לתיעוד.
2. תומך גם בחיפושי מסמכים.
3. אפשר לבטל CSS המוגדר כברירת מחדל על ידי קוד מותאם אישית; חלק מהשליטה על HTML אפשרי באמצעות קובצי rst.

חסרונות:

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

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

יתרונות:

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

חסרונות:

1. ייתכן שלא יספק את מבנה התיעוד הטוב ביותר.

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

יתרונות:

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

חסרונות:

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

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

יתרונות:

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

חסרונות:

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

= שימוש ב-MKDocs פתרון זה מספק במקומו פתרון Markdown חלופי.

יתרונות:

1. זה כרוך בקידוד מינימלי (שוב).
2. לכתוב יותר, הגישה של Code פחות.

חסרונות:

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

= שימוש ב-VueJS +StorybookJS בדרך כלל מקובל להשתמש ב-VueJS ובמאגרי האחיות שלו.

יתרונות:

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

חסרונות:

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

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