דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- אלקטרון
- כתב טכני:
- מיסטר זהב
- שם הפרויקט:
- תהליך מדריך השימוש באלקטרון
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
סיכום פרויקט
Electron הוא אחד הכלים הפופולריים ביותר לבניית אפליקציות לשולחן העבודה בפלטפורמות שונות באמצעות JavaScript , HTML ו-CSS. אוסף של אפליקציות שמבוססות על Electron כולל כמעט 900 רשומות, והרשימה הזו ממשיכה לגדול כל הזמן. חלק מכלי הפיתוח הפופולריים ביותר, כמו Visual Studio Code, Atom, Postman, Slack ו-GitKraken מבוססים על Electron.
הפופולריות של Electron טבועה בעקומת הלמידה הפשוטה ובסף הכניסה הנמוך – כל מי שמכיר JavaScript , HTML וסטאק CSS יכול ליצור אפליקציה משלו. שיעורי הצמיחה הכוללים העצומים מכתיבים את הצורך ליצור מדריכים ומדריכים לתחילת העבודה, שקל להבין ולהשתמש בהם.
מטרת הפרויקט היא להביא את האמון של בוני אפליקציות חדשים במסגרת Electron ולספק להם חוויה עקבית ויעילה בפיתוח אפליקציות Electron משלהם.
בעיות בפרויקט
הרשימה הבאה היא רשימה של הבעיות הקריטיות ביותר שקשורות לתיעוד של מדריכי Electron: 1. נקודת התחלה לא ברורה ופרטי הקדמה לא אינטואיטיביים לגבי שלבי פיתוח האפליקציה 2. מידע מפוזר ומיותר שקשור לתהליך פיתוח האפליקציה 3. קטעים לא מאורגן של ההוראות של 'איך מתחילים', ללא מקור מהימן אחד
הצעה לפרויקטים
בהתאם ליעד הפרויקט ולבעיות שצוינו למעלה, ריכזנו כאן רשימה של השיפורים המוצעים: 1. מעדכנים את קווי העזר הקיימים. כדי שהצעדים הראשונים יהיו חלק ועקביים, צריך לעדכן את המסמכים הבאים באופן הדרגתי מהפשוט למורכבות יותר: - סביבת המפתחים - כתיבת אפליקציית האלקטרונים הראשונה - הוספת תכונות לאפליקציה (יצירת דף סיכום) - אריזה והפצה של אפליקציה 2. שינוי המבנה של ספריית התיעוד. כדי להראות למפתחים חדשים מה הדבר החשוב ביותר לתחילת העבודה ומה ניתן להחשיב כשלבים נוספים, דף Docs צריך לכלול חלוקה חזותית וחלוקה ההקשרית של השלבים כדי להפוך את היישום הראשון לפעיל במהירות האפשרית. שינוי המבנה כולל גם הדרכה לגבי השלבים הבאים האפשריים. 3. ארגון ואיחוד של מסמכי פיתוח אפליקציות. כל התכונות צריכות לכלול סדרה מאוחדת של הוראות להתקנה/הפעלה של האפליקציה, איך להתחיל לעבוד במהירות, איך לעבוד עם אפליקציה אחרי ההשקה הראשונה ואיך להפיץ אותה. 4. כלול מאגר נתונים אלקטרוני-api-demos בתיעוד. המאגר Electron-api-demos מכיל סדרה של דוגמאות שמראות איך להוסיף תכונות לאפליקציה Electron. המידע הזה צריך להיכלל במדריך 'הוספת תכונות לאפליקציה' בהתאם לאסטרטגיית תוכן ממקור אחד מרכזי. 5. שלבו דוגמאות של כינור אלקטרוני בתיעוד. השלב הזה יקל על מפתחים חדשים לראות איך קטע קוד מסוים פועל, בלי שיצטרכו לחזור על השלבים האלה באופן ידני. השילוב כולל כתיבת דוגמאות קוד למדריכים המעודכנים והוספת הלחצן "הפעלה בכינור" לבלוקים של קוד.
מהלך המשחק
תקופת הבדיקה של בקשת ההצטרפות - הכירו את הקהילה ואת האנשים שאתם צריכים לעבוד איתם. כאן אפשר ללמוד על מדריכים ושיטות מומלצות להוספת תוכן מהקהילה. מוסיפים את התוכן הראשון. חיבורים קהילתיים – חוקרים את הקהילה. בדקו את מצב התיעוד הנוכחי של Electron. זהו נקודות חלשות. שבוע 1 – התאמה למנטורים לגבי אבני הדרך והחומרים של הפרויקט שבוע 2 – שינוי סביבת המפתחים וכתיבת הדפים הראשונים באפליקציית האלקטרונים שבוע 3 – שינוי ארכיטקטורת האפליקציה, הוספת תכונות לאפליקציה, אריזת האפליקציה ודפי ההפצה. יצירת דף סיכום עם רשימה של תכונות שניתן להוסיף לאפליקציה שבוע 4 - בנייה מחדש של ספריית המסמכים שבוע 5 - הכנת תבנית לאופן השילוב של אלקטרון-API-הדגמות בתיעוד העיקרי שבועות 6-7 - העברת המאגר Electron-api-demos שבוע 8 – הכנת תבנית של אופן השילוב של Electron Fiddle. כותבים את הדוגמה הראשונה. שבועות 9 עד 10 – שילוב כינור האלקטרונים בתיעוד הראשי שבוע 11 – השלמת מבנה התיעוד והדפים המרכזיים לאחר העברת המאגר Electron-api-demos ודגימות Electron Fiddle שבוע 12 – הערכת התוצאות
פירוט יעדים מפורט
תקופת הבדיקה של הבקשה החלק הראשון של התקופה יהיה מיועד לבדיקת ערוצי הקהילה וקוד המקור וליצירת קשר עם האנשים האחראים לפרויקט.
החלק השני של התקופה יהיה מיועד לבדיקת תרבות התרומות באופן כללי, לבחינת המדריכים והשיטות המומלצות לתרומות. זו תהיה הפעם הראשונה שמוסיפים תכנים כדי לראות איך פועל הזרימה.
גיבוש קהילה
זמן זה יוקדש לבדיקה מעמיקה יותר של תיקיית התיעוד ולגבי מפת הדרכים שלה. על סמך המידע הזה ניתן לזהות נקודות חולשה (למשל, חלקים חסרים או חסרים) שכדאי לשפר. יוצרים בקשות משיכה (כשאפשר) כדי למלא את הפערים.
שבוע 1 - שבוע 2
השבוע הראשון יוקדש לתקשורת עם מנטורים על מנת להתאים את עמם לאבני הדרך הצפויות ולעמוד בזמנים.
השבוע השני עוסק בתיקון הדפים של סביבת המפתחים ובכתיבת דפי אפליקציית האלקטרונים הראשונה. בדף 'סביבת המפתחים' היא תכלול שכתוב של הסקירה הכללית וההגהה. בדף 'כתיבת האפליקציה האלקטרונית הראשונה שלך', הדף יכלול הגדרת הדף כמדריך עקבי, עם נקודות התחלה וסיום ברורות, הסרת מידע מיותר (כגון שני גושי קוד דומים תחת 'פיתוח אלקטרונים במעטפת' ו'התנסות בדוגמה זו').
חומרים תוצרים: מדריכי מבוא מתוקנים וקלים להבנה בנושא התחלה מהירה עם יישומים של Electron.
שבוע 3
השבוע מוקדש לנושאים הבאים: 1. שיפורים בדף 'ארכיטקטורת אפליקציות'. כולל: - שכתוב של המידע הקיים בקטע 'תהליכים ראשיים' ו'תהליכים לעיבוד מידע' כדי להפוך אותו לפשוט ואינטואיטיבי יותר לקוראים החדשים - הוספת ייצוג ויזואלי של הארכיטקטורה, אופן החיבור, האופן שבו הם מתקשרים וההבדלים העיקריים ביניהם. דוגמאות לתמונות: אחת, שתיים, שלוש (איכות נמוכה). 2. איחוד של המידע על כל התכונות שניתן להוסיף ליישום Electron. הפעולות האלה כוללות שכתוב של המדריכים כדי שיהיו להם קבוצה מאוחדת של הוראות להתקנה/הפעלה של תכונה יחד עם דוגמה לאופן הפעולה של התכונה. בנוסף, ייווצר דף חדש (סיכום) שבו מפורטות כל התכונות הזמינות לשימוש. ההוראות המאוחדות יכולות להיראות כך: - סקירה כללית - דוגמה: - דוגמת קוד - דוגמה חזותית (כאשר הדבר אפשרי)
- פישוט הדף 'הפצת אפליקציות'. זה כולל: א. מיזוג אריזת אפליקציות למדריך הפצת אפליקציות ב. חלוקת שיטות הפצה לפעולות אוטומטיות וידניות ג. שימוש בחליפת אלקטרון כדוגמה להפצה אוטומטית ד. לקיחת מידע על Asar מהדף 'אריזת אפליקציות' ותיאור ההעתקה של קובצי המקור ויצירת ארכיון Asar כדוגמאות להפצה ידנית. #### WEEK 4 השבוע מוקדש לשינוי המבנה של ספריית המסמכים. היא כוללת:
1 - חלוקה של המדריכים הקיימים בשלוש קטגוריות לפחות: א. מדריך למתחילים ב. למידת היסודות ג. שלבים מתקדמים
הקטגוריה של מדריך למתחילים תכיל את המדריכים הבסיסיים (התקנה, הגדרה, הפצה) ליצירת סדרה עקבית של מדריכים שיאפשרו למשתמשים חדשים להתחיל מאפס. כל מדריך צריך לכלול קישורים למדריכים הקודמים/הבאים בסדרה.
המבנה עשוי להיראות כך: 1. דרישות מוקדמות 2. מתקינים את Electron 3. יצירת אפליקציה בסיסית 4. אריזת/הפצה של האפליקציה
לאחר השלמת החלק למתחילים, המשתמש יכיר את העקרונות הבסיסיים של אופן הפעולה של יישומי אלקטרונים ויכיל יישום אלקטרונים שפועל באופן מלא וניתן להפצה.
הקטגוריה 'למידת הבסיס' תכלול את המדריכים שמטרתם להעמיק את הידע לגבי Electron ולהרחיב את היישום שנוצר בחלקים למתחילים. המדריכים האלה כוללים: - ארכיטקטורת אפליקציות - הוספת פיצ'רים לאפליקציה - לוחות אינסטרומנטלים ורכיבי CLI
הקטגוריה 'שלבים מתקדמים' תכלול מדריכים מתקדמים יותר שמיועדים להגדרה ולכוונון של אפליקציית Electron: - בדיקה וניפוי באגים - נגישות - אבטחה - עדכונים
2 - הפחתת מספר דפי התיעוד. הגרסה הנוכחית של המסמך מכילה מידה מסוימת של תוכן חופף והוראות ללא שיוך לקטגוריה. לדוגמה: - התקנה והתקנה של אלקטרון בתוך 'כתיבת האפליקציה הראשונה' - אריזה ואריזה של האפליקציה לקובץ בהפצת האפליקציה - הוראות ללא שיוך לקטגוריה 'פירוט' ו'מתקדם': הצעה: להעביר את המסמכים הבאים ל-GitHub ולא לכלול אותם בתיעוד הראשי. המסמכים האלה מתייחסים ספציפית להנחיות לפיתוח אלקטרונים, ומאגר המקור הוא המקום הראשון לחפש אותם: - פיתוח אלקטרונים - פיתוח של Chromium - פיתוח V8 - בעיות באלקטרון - כתמים באלקטרון - שליפת בקשות - מבנה ספריית קוד מקור - בדיקה - סגנון תכנות
הרעיון העיקרי של הפחתת מידע הוא להיפטר ממספר מדריכים זמינים, לחבר את חלקי המידע המפוזרים יחד עם חידות המידע ולתת למשתמשים חדשים גרסה מובנית, נוחה יותר לניווט וידידותית למשתמש של התיעוד של Electron.
שבועות 5 עד 7
שבוע 5 יוקדש להכנת תבנית (דרך) לאופן שבו ישולבו אלקטרוני-API-דמו בתיעוד העיקרי. התבנית הזו עשויה להיראות כך: 1. בתיעוד הראשי, בקטע 'הוספת תכונות לאפליקציה', יוצרים את הקטגוריות שמיוצגות בהדגמות האלקטרוניות. 2. מעבר על כל אחת מהקטגוריות מעבירים את הדוגמאות להדגמה אל התיעוד הראשי: - ניתן לקחת דוגמאות קוד מקוד המקור או מהתיאור של התכונה המתאימה באפליקציה - אחרי כל דוגמה שהועברה, צריך להופיע התיאור המשויך - יש להעביר כל דוגמה של צאצא (לדוגמה, תיבת דו-שיח של שגיאה כצאצא של תיבות הדו-שיח 'שימוש במערכת') בשדה ההורה שלו
הערה 1: יש דוגמאות הקיימות גם ב-Electronic-api-demos וגם בתיעוד הראשי (לדוגמה, מקשי קיצור, גרירה ושחרור). במקרה הזה, יש עדיפות גבוהה יותר לדוגמה מהדוגמאות של האלקטרונים-api-דמו, ומעליה להתעלם מהדוגמה בתיעוד הראשי.
הערה 2: דוגמאות רבות ביישום Electron-api-demos כוללות תצוגה מקדימה של הדגמה חיה של התכונה או הפונקציונליות שמתוארות. המערכת תתעלם מהפונקציונליות הזו עד לשילוב Electron Fiddle בשבועות 9 עד 10.
- מעדכנים את הדף שבו מפורטים כל התכונות הזמינות לשימוש (שנוצרו במהלך שבוע 3) בהתאם להיררכיה החדשה של הדוגמאות.
שבוע 6 ו-7 יוקדשו להעברת דוגמאות של אלקטרונים-API-דמו לתיעוד העיקרי, בהתאם לתבנית המתוארת למעלה. בשלב האחרון, צריך למחוק את המאגר Electron-api-demos או להוציא אותו משימוש.
שבועות 8 עד 10
שבוע 8 יוקדש להכנת תבנית (דרך) לאופן שבו 'כינור אלקטרוני' ישולב בתיעוד העיקרי. היוזמה הזו כבר הושקה על ידי חברים של Electron יחד עם מתנדבים מהקהילה (כדאי לעיין בפרטים בחשבונית מס' 20442), אבל היא דורשת סיום מתאים.
כדי להמשיך עם דגימות כינור, התבנית הבסיסית עשויה להיראות כך: 1. בוחרים דוגמה מתוך המסמכים הראשיים (למשל, המדריך למתחילים). בשלב הזה, התיעוד אמור לכלול גם דוגמאות של Electron-api-demos. 2. יוצרים מחדש את הדוגמה ב-Elecron Fiddle (משתמשים בקוד לדוגמה או בקוד המקור כנקודת התחלה). 3. שומרים את הכינור באופן מקומי בתיקייה. 4. מעבירים את הדוגמה אל /docs/fiddles/[CATEGORY]/[section]/[DEMO]. * רשימת הדוגמאות שהושלמו מתוארת בקטע "רשימת הדגמות" של הבעיה. 5. מוסיפים את הלחצן 'הפעלה בכינור' כפי שמתואר בתגובה הראשונית בבעיה מס' 2848.
שבועות 9 ו-10 יוקדשו לשילוב דוגמאות של Electron-api-demo (שכבר הומרו לכנורות) בתיעוד העיקרי בהתאם לתבנית המתוארת למעלה.
שבוע 11
השבוע יוקדש במלואו לסיום פרויקט הכתיבה לאחר מיגרציה מוצלחת של המאגר Electron-api-demos ודגימות Electron Fiddle. זה כולל: - בדיקה שכל דוגמאות הקוד הקיימות כוללות את הלחצן "הפעלה ב-Fiddle" - בדיקה שכל דוגמאות הקוד הקיימות פועלות באופן תקין כ-Fiddles - בדיקה שהתיעוד הראשי לא מתייחס יותר למאגר Elron-api-demos
שבוע 12
השלמת העבודה שהושלמה. בדיקות קבלה.