פרויקט אלקטרוני

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

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

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

Electron

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

זהב גדול

שם הפרויקט:

Electron Tutorial Flow

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

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

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

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

Electron הוא אחד הכלים הפופולריים ביותר לפיתוח אפליקציות למחשבים בפלטפורמות שונות באמצעות JavaScript,‏ HTML ו-CSS. באוסף האפליקציות שנוצרו ב-Electron יש כמעט 900 רשומות, והרשימה הזו הולכת וגדלה. חלק מכלי הפיתוח הפופולריים ביותר, כמו Visual Studio Code,‏ Atom,‏ Postman,‏ Slack ו-GitKraken, מבוססים על Electron.

הפופולריות של Electron נובעת מעקומת הלמידה הפשוטה שלו ומסף הכניסה הנמוך – כל מי שמכיר את סטאק JavaScript,‏ HTML ו-CSS יכול ליצור אפליקציה משלו. שיעורי הצמיחה הכוללים הגבוהים מחייבים אותנו ליצור מדריכים ומדריכים למתחילים שקל להבין אותם ולהשתמש בהם.

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

בעיות בפרויקט

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

הצעת פרויקט

בהתאם ליעד הפרויקט ולבעיות שמפורטות למעלה, הנה רשימה של השיפורים המוצעים: 1. מעדכנים את המדריכים הקיימים. כדי שהשלבים הראשונים יהיו חלקים ועקביים, צריך לעדכן את המסמכים הבאים ולהתחיל מהפשוט למורכב: - סביבת הפיתוח - כתיבת האפליקציה הראשונה ב-Electron - הוספת תכונות לאפליקציה (יצירת דף סיכום) - אריזה והפצה של אפליקציות 2. שינוי המבנה של ספריית המסמכים. כדי להראות למפתחים חדשים מה חיוני כדי להתחיל לעבוד ומה אפשר להחשיב כשלבים נוספים, בדף המסמכים צריך להיות חלוקה חזותית ותרבותית של השלבים כדי להפעיל את האפליקציה הראשונה במהירות האפשרית. תהליך השינוי המבני כולל גם הנחיות לגבי השלבים הבאים האפשריים. 3. ארגון ואיחוד של מסמכי פיתוח אפליקציות. לכל התכונות צריכה להיות קבוצה אחידה של הוראות להתקנה או להפעלה, להתחלה מהירה, לעבודה עם האפליקציה אחרי ההפעלה הראשונה ולהפצה שלה. 4. הוספת המאגר electron-api-demos למסמכי העזרה. המאגר electron-api-demos מכיל קבוצה של דוגמאות שממחישות איך להוסיף תכונות לאפליקציית Electron. צריך לכלול את המידע הזה במדריך 'הוספת תכונות לאפליקציה' כדי שיהיה תואם לאסטרטגיית התוכן של מקור מהימן אחד. 5. שילוב דוגמאות מ-Electron Fiddle במסמכי התיעוד. השלב הזה יאפשר למפתחים חדשים לראות בקלות איך קטע קוד מסוים פועל, בלי שתצטרכו לחזור על השלבים באופן ידני. השילוב כולל כתיבת דוגמאות קוד למדריכים המעודכנים והוספת הלחצן 'הפעלה ב-Fiddle' לקטעי קוד.

מהלך המשחק

תקופה של בדיקת בקשות – הכירו את הקהילה והאנשים שאיתם כדאי לעבוד. מדריכים ושיטות מומלצות לתרומה לקהילה. מוסיפים את התכנים הראשונים. יצירת קשרים בקהילה – היכרות עם הקהילה. בדיקת המצב הנוכחי של תיעוד Electron. זיהוי נקודות חולשה. שבוע 1 – תיאום עם החונכים לגבי אבני הדרך והעבודות של הפרויקטים שבוע 2 - שינוי סביבת המפתחים וכתיבת הדפים של אפליקציית האלקטרונים הראשונה שבוע 3 - שינוי ארכיטקטורה של אפליקציות, הוספת תכונות לאפליקציה, לדפי אריזת האפליקציות ולדפי ההפצה. יצירת דף סיכום עם רשימה של תכונות שאפשר להוסיף לאפליקציה שבוע 4 – שינוי המבנה של ספריית המסמכים שבוע 5 – הכנת תבנית לאופן שבו electron-api-demos ישולבו במסמכים הראשיים שבועות 6-7 – העברה של המאגר electron-api-demos שבוע 8 – הכנת תבנית לאופן שבו Electron Fiddle ישולבו במסמכים הראשיים. כותבים את הדוגמה הראשונה. שבוע 9 עד שבוע 10 – שילוב של Electron Fiddle במסמכי העזרה הראשיים שבוע 11 – סיום של המבנה והדפים של מסמכי העזרה הראשיים אחרי העברת המאגר electron-api-demos והדוגמאות של Electron Fiddle שבוע 12 – הערכת התוצאות

פירוט של יעדים

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

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

קישור בין חברי הקהילה

הפעם נתמקד בבדיקה מעמיקה יותר של תיקיית המסמכים, יחד עם מפת הדרכים שלה. על סמך המידע הזה תוכלו לזהות נקודות חולשה (למשל, חלקים חלקיים או חסרים) שאפשר לשפר. יוצרים בקשות משיכה (אם אפשר) כדי למלא את הפערים.

שבוע 1 – שבוע 2

השבוע הראשון יוקדש לתקשורת עם המנטורים כדי לקבוע את אבני הדרך הצפויות ואת מועד ההגשה שלהן.

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

תוצרים: מדריכים מעודכנים וקלים לקריאה למתחילים בנושא תחילת העבודה עם אפליקציות Electron.

שבוע 3

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

1. פישוט של הדף 'הפצת אפליקציות'. השינויים כוללים: א. מיזוג של Application Packaging למדריך Application Distribution ב. חלוקה של שיטות הפצה ל'אוטומטיות' ו'ידניות' ג. שימוש ב-electron-forge כדוגמה להפצה אוטומטית ד. שימוש במידע על asar מהדף Application Packaging ותיאור של העתקת קובצי מקור ויצירת ארכיון asar כדוגמה להפצה ידנית. #### שבוע 4 השבוע יוקדש לשינוי המבנה של ספריית המסמכים. היא כוללת:

1 – חלוקת המדריכים הקיימים לפחות לשלוש קטגוריות: א. מדריך למתחילים ב. לימוד היסודות ג. שלבים מתקדמים

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

המבנה עשוי להיראות כך: 1. דרישות מוקדמות 2. מתקינים את Electron 3. יוצרים אפליקציה בסיסית 4. לארוז/להפיץ את הבקשה

אחרי השלמת הקטע 'מדריך למתחילים', המשתמש יבין את העקרונות הבסיסיים של אופן הפעולה של אפליקציות Electron, ויהיה לו אפליקציית Electron שפועלת באופן מלא וניתנת להפצה.

בקטגוריה 'לימוד היסודות' יהיו מדריכים שמטרתם לשפר את הידע שלכם על Electron ולהרחיב את האפליקציה שנוצרה בקטעים 'תחילת העבודה'. המדריכים האלה כוללים: - ארכיטקטורת אפליקציות - הוספת תכונות לאפליקציה - תבניות בסיסיות וממשקי CLI

בקטגוריה 'שלבים מתקדמים' יהיו מדריכים מתקדמים יותר שמטרתם להגדיר ולשפר את אפליקציית Electron: - בדיקה וניפוי באגים - נגישות - אבטחה - עדכונים

2 - צמצום מספר דפי המסמכים. הגרסה הנוכחית של המסמכים מכילה תוכן חופף מסוים והוראות שלא מסווגות. לדוגמה: - Installation ו-Installing Electron בקטע 'כתיבת האפליקציה הראשונה' - Application Packaging ו-Packaging Your App into a File בקטע 'הפצת האפליקציה' - הוראות ללא קטגוריה בקטגוריות 'בפרטים' ו'מתקדם': הצעה: כדאי להעביר את המסמכים הבאים ל-GitHub ולהחריג אותם מהמסמכי העזרה הראשיים. המסמכים האלו ספציפיים להנחיות לפיתוח אלקטרונים, ומאגר המקור הוא המקום הראשון לחפש אותם: - פיתוח אלקטרון

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

שבוע 5 עד שבוע 7

שבוע 5 יוקדש להכנת תבנית (דרך) לשילוב של electron-api-demos במסמכי התיעוד הראשיים. התבנית הזו עשויה להיראות כך: 1. במסמך הראשי, בקטע 'הוספת תכונות לאפליקציה', יוצרים את הקטגוריות שמיוצגות ב-electron-api-demos 2. בודקים כל אחת מהקטגוריות ומעבירים את דוגמאות הדגמה למסמכי העזרה הראשיים: - אפשר להעתיק דוגמאות קוד מקוד המקור או מהתיאור של התכונה המתאימה באפליקציה - אחרי כל דוגמה שמועברת צריך להוסיף את התיאור המשויך - צריך להעביר כל דוגמה צאצאית (לדוגמה, תיבת דו-שיח של שגיאה כצאצא של 'שימוש בתיבת דו-שיח מערכתית') מתחת להורה שלה

הערה מס' 1: יש דוגמאות שקיימות גם ב-electron-api-demos וגם במסמכי התיעוד הראשיים (לדוגמה, מקשי קיצור, גרירה ושחרור). במקרה כזה, הדוגמה מההדגמות האלקטרונים-api-demo תקבל עדיפות ותתעלם מהדוגמה בתיעוד הראשי.

הערה מס' 2: בדוגמאות רבות באפליקציה electron-api-demos יש תצוגה מקדימה של הדגמה פעילה של התכונה או הפונקציונליות המתוארת. המערכת תתעלם מהפונקציונליות הזו עד לשילוב של Electron Fiddle בשבועות 9-10.

1. מעדכנים את הדף שבו מפורטות כל התכונות הזמינות לשימוש (שנוצר בשבוע 3) בהתאם להיררכיה החדשה של הדוגמאות.

השבועות 6 ו-7 יוקדשו להעברת דוגמאות של electron-api-demos למסמכי העזרה הראשיים, בהתאם לתבנית שמתוארת למעלה. בשלב האחרון, צריך למחוק או להוציא משימוש את המאגר electron-api-demos.

שבוע 8 עד 10

שבוע 8 יעסוק בהכנת תבנית (דרך) לאופן שבו Electron Fiddle ישולב בתיעוד הראשי. היוזמה הזו כבר הושקה (בדקו את הפרטים בנושא מס' 20442) על ידי חברי Electron יחד עם מתנדבים בקהילה, אבל נדרש סיכום מתאים.

כדי להמשיך עם דוגמאות ל-Fiddle, התבנית הבסיסית עשויה להיראות כך: 1. בוחרים דוגמה מהמסמכי העזרה הראשיים (לדוגמה, מדריך למתחילים). בשלב הזה, המסמכים צריכים לכלול גם דוגמאות ל-electron-api-demos. 2. יוצרים מחדש את הדוגמה ב-Electron Fiddle (באמצעות קוד לדוגמה או קוד המקור כנקודת התחלה). 3. שומרים את הקוד ב-Fiddle באופן מקומי בתיקייה. 4. מעבירים את הדוגמה אל /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * רשימת הדוגמאות שהושלמו מתוארת בקטע 'רשימת הדגמות' בבעיה. 5. מוסיפים את הלחצן 'הפעלה ב-Fiddle' כפי שמתואר בתגובה הראשונה בבעיה מס' 2848.

השבועות 9 ו-10 יוקדשו לשילוב דוגמאות של electron-api-demos (שכבר הומרו ל-Fiddles) במסמכי העזרה הראשיים, בהתאם לתבנית שמתוארת למעלה.

שבוע 11

השבוע נתרכז בהשלמת פרויקט הכתיבה אחרי שנסיים את המיגרציה של המאגר electron-api-demos והדוגמאות של Electron Fiddle. העדכונים כוללים: - בדיקה שכל דוגמאות הקוד הקיימות כוללות לחצן 'Launch in Fiddle' (הפעלה ב-Fiddle) - בדיקה שכל דוגמאות הקוד הקיימות פועלות כראוי בתור Fiddles - בדיקה שהתיעוד הראשי כבר לא מתייחס למאגר Eltron-api-demos

שבוע 12

סיום העבודה שהושלמו. בדיקות אישור.