בדף הזה מופיעים הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Docs ל-Google Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- BRL-CAD
- כותבים טכניים:
- סאהיבקאור
- שם הפרויקט:
- מדריך למתחילים בנושא BRL-CAD
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
מדריך למתחילים ב-BRL-CAD
תקציר הפרויקט
מטרת הפרויקט היא ליצור מסמכי עזרה למשתמשים שהם לא רק חדשים ב-BRL-CAD, אלא גם חדשים בקוד פתוח.
למה דווקא הפרויקט הזה
כשביקרתי לראשונה באתר של BRL-CAD, לא הכרתי את קוד המקור הפתוח ואת BRL-CAD, והיה לי קשה לעכל את כמות המידע שמוצגת בו בבת אחת. אבל עמוק בתוכי ידעתי שיש כאן הרבה מה ללמוד. לכן רציתי ליצור מסמכי עזרה למשתמשים חדשים כמוני, כדי שתוכלו להפיק הרבה מהקהילה הזו ולהתחיל לעבוד בקלות.
יעדים
הפרויקט הזה יטרגט משתמשים חדשים. אז הנה כמה נקודות שהמסמכי העזרה שלי נועדו להשיג: כדי להבטיח שלמשתמשים חדשים יהיה נוח: מסמכי העזרה האלה מיועדים למשתמשים חדשים, לא רק למשתמשים חדשים ב-BRL-CAD אלא גם למשתמשים חדשים בקוד פתוח.
כדי להשיג זאת, אעשה את הפעולות הבאות:
- חשוב לוודא שהציון של המסמך לפי מדד פלש-קינקייד יהיה לפחות 50. לפי שיטת פלש-קינקייד, ככל שהציון גבוה יותר, כך קל יותר להבין את הטקסט. אפשר לבדוק את ציון הקריאוּת שלו באינטרנט.
- כדאי להשתמש ברשימות תבליטים או ברשימות ממוספרות כדי שהקוראים לא יתעייפו או יתבלבלו מפסקאות ארוכות.
- כדאי להשתמש בפסקה ובמשפטים קצרים יותר, כי קריאה והבנה של משפטים ארוכים דורשות יותר מאמץ מנטלי.
- כדאי להשתמש בכותרות משנה כדי לפצל את הטקסט. תיעוד מובנה: תיעוד מובנה ממלא תפקיד חיוני בהדרכת משתמשים חדשים. זה מונע מהם ללכת לאיבוד, וליידע אותם לאן הם הולכים ומה הם עושים. כדי לעשות זאת, בניתי מפת חשיבה גסה, שיכולה לעזור לנו לתעד את המדריך למתחילים הזה בצורה מאורגנת.
תיאור הפרויקט
הפרויקט הזה מתמקד בכתיבת מסמכי עזרה למשתמשים חדשים שרוצים להתחיל להשתמש בתוכנה הזו.
בהמשך מופיעה דוגמה לאופן שבו אני מתכוון לשפר את התיעוד.
מבוא בסיסי: BRL-CAD (מבוטא be-are-el-cad) הוא תוכנת תכנון בעזרת מחשב (CAD) ליצירת מודלים של מוצקים באמצעות גיאומטריה מוצקה גנרטיבית (CSG). זוהי מערכת חזקה של מודלים מוצקים בקוד פתוח לפלטפורמות שונות, לתכנון תלת-ממדי בעזרת מחשב ולתצוגה חזותית גרפית. אתה לא יכול להזיז את הראש? ננסה להסביר. קוד פתוח: תוכנה בקוד פתוח היא תוכנה עם קוד מקור שכל אחד יכול לבדוק, לשנות ולשפר. BRL-CAD היא תוכנת קוד פתוח, ולכן אתם מוזמנים לתרום ולשפר את BRL-CAD. תכנון בעזרת מחשב (CAD): במילים פשוטות, CAD הוא שימוש בתוכנות מחשב כדי ליצור ייצוג גרפי דו-מימדי או תלת-מימדי של אובייקטים פיזיים. מערכת יצירת מודלים תלת-ממדיים: מערכת BRL-CAD מתמקדת ביצירת מודלים תלת-ממדיים ב-CAD. יצירת מודלים תלת-ממדיים שונה מסוגים אחרים של יצירת מודלים גיאומטריים בכך שהיא מתמקדת בדיוק פיזי ומתאר מלא של המרחב התלת-ממדי. הוא מדמה אובייקט גם באופן פנימי וגם באופן חיצוני. גיאומטריה מוצקה גנרטיבית (CSG): CSG מאפשר לייצג מודלים מורכבים כסדרה של פעולות בוליאניות בין פרימיטיבים. האובייקטים המוצקים הפשוטים ביותר המשמשים לייצוג נקראים 'פרימיטיביים'. כאן מוסבר על CSG ברמה הבסיסית.
*כפי שצוין בתיאור של רעיון הפרויקט: במסמכי התיעוד יפורטו לפחות התקנה בסיסית, תיאור כללי של היכולות, עקרונות היצירה של BRL-CAD, שימוש בסיסי בכלים העיקריים, יצירה, ייבוא/ייצוא, ניתוח ורינדור.
בהמשך מופיעים פתיחים קצרים לגבי כל אחד מחלקי התיעוד.
- התקנה בסיסית: אני אוסיף מדריך מפורט להתקנת תוכנת BRL-CAD יחד עם צילומי המסך הנדרשים. המדריך למתחילים הוא מקום טוב להתחיל בו למשתמשים חדשים. לדעתי, חסרים כמה דברים:
- השלבים במדריך למתחילים הזה לא מסומנים בסימני נקודה או במספרים. קיים מדריך מפורט עם צילום מסך בסוף כל שלב, מגדילה את הסיכוי שהמשתמש יתלהב למדריך.
- תיאור כללי של היכולות: הקטע הזה מכיל את כל האזורים שבהם ל-BRL-CAD יש יכולת להראות פלאים. דרך טובה יותר למשוך תשומת לב לחלק הזה היא להשתמש בתרשים.
- עקרונות בניית המודלים של BRL-CAD: לחלק הזה יהיה צורך בהסבר נוסף, כי המשתמשים יוכלו להבין טוב יותר את BRL-CAD ברגע שמבין היטב את עקרונות המודלים האלו.
- שימוש בסיסי בכלים העיקריים: בקטע הזה יהיו מדריכים נפרדים לגבי הכלים העיקריים והשימוש הבסיסי בהם. אלה יהיו מדריכים מפורטים.
- ייצוא/ייבוא: המשתמשים ילמדו על ספריית ההמרות של Geometry. אחד השימושים הנפוצים ביותר של BRL-CAD הוא להמיר גיאומטריה מפורמט אחד לפורמט אחר. בקטע הזה נדון בממירים לייצוא ולייבוא.
- רינדור: נסקור את העקרונות הבסיסיים של רינדור ואת הצורך בו בתוכנה שלנו. המשתמשים גם ילמדו איך ליצור עיבוד תמונה ב-BRL-CAD.
מלבד זאת, המיקוד הוא גם בנקודות הבאות:
- בתחילת התיעוד תהיה הבנה בסיסית לגבי מהות התוכנה הזו.
- איך משתמשים יכולים להתחבר לקהילה הזו של קוד פתוח, קישור לצ'אט של BRL-CAD ב-Zulip.
- ברמה המופשטת, כדאי להוסיף הומור למסמכי העזרה ולבקש מהמשתמשים החדשים לא להתייאש ממונחים מורכבים. אהבתי את הגישה האמפתית שנעשה בה שימוש בדף הראשי של הוויקי של BRL-CAD.
- הוא יכלול צילומי מסך של דברים מדהימים שהמשתמשים יכולים לעשות באמצעות התוכנה הזו.
אבני דרך
יולי (תקופת בדיקת ההצעה)
- אעיין במדריכים הקיימים כדי להכיר טוב יותר את התוכנה ואת מסמכי התיעוד שלה.
- אטפל בשיפורים במסמכים הקיימים.
1 באוגוסט עד 7 באוגוסט (יצירת קשרים בקהילה)
- דיון עם המנטורים על הפרויקט.
- שיפור פרטי הפרויקט.
- מבצעים את השינויים הנדרשים בנקודות הציון (אם יש צורך).
8 באוגוסט עד 14 באוגוסט
- היכרות עם Docbook XML
15 באוגוסט עד 21 באוגוסט
- כתיבת מסמכי עזרה ל'מבוא בסיסי ל-BRL-CAD'
- כתיבת מדריך מפורט ל'התקנה בסיסית'
22 באוגוסט עד 27 באוגוסט
- סקירה של היכולות השונות של BRL-CAD ורישום שלהן יחד עם צילומי מסך.
- כדאי להסביר על תכונות ספציפיות בדף נפרד.
28 באוגוסט עד 3 בספטמבר
- ממשיכים לעבוד על מסמכים ספציפיים כדי לבדוק את היכולות.
4 בספטמבר עד 10 בספטמבר
- עבודה על עקרונות בניית מודלים.
- הסבר על כל עקרונות הבנייה של מודלים.
11 בספטמבר עד 17 בספטמבר
- עבודה על שימוש בסיסי בכלים העיקריים.
- עורכים רשימה של רעיונות לתיעוד של שימוש בסיסי בכל כלי.
18 בספטמבר עד 24 בספטמבר
- תיעוד השימוש בכל כלי.
25 בספטמבר עד 1 באוקטובר
- עבוד על בניית מודלים כדי ליצור מודל מוצק למדריך ולכתוב טיוטה לצדו.
2 באוקטובר עד 8 באוקטובר
- שיפור הטיוטה של המודלים.
2 באוקטובר עד 8 באוקטובר
- ללמוד על ממירים לייצוא וליבוא.
9 באוקטובר עד 15 באוקטובר
- הכנת מסמכי הייצוא והייבוא.
- מתחילים לעבוד על העיבוד.
16 באוקטובר עד 22 באוקטובר
- תיעוד המדריך בנושא עיבוד.
23 באוקטובר עד 29 באוקטובר
- בדיקת כל המסמכים.
30 באוקטובר עד 5 בנובמבר
- עבודה עם Docbook XML
6 בנובמבר עד 12 בנובמבר
- מבקשים ממנחים ומחברים אחרים בקהילה לבדוק את התוכן ולעבוד על השינויים.
- דיון עם המנטורים וביצוע השינויים הסופיים.
12 בנובמבר עד 22 בנובמבר
- תהליך הדיון והשינויים.
- הוספת ליטושים אחרונים למסמכים.
פרטים עליי
אני כותב מאז ימי בית הספר. הייתי חוזרת מבית הספר וכותבת על כל מה שקרה לי באותו יום, מה גרם לי ליהנות או להרגיש רע. תמיד אהבתי לכתוב את השגיאות שביצעתי ואת הדרכים שבהן אוכל לשפר אותן.
במהלך ההכשרה שלי כמעצבת אתרים, התבקשנו לכתוב מה אנחנו לומדים מדי יום. רציתי לתעד כמה מהבעיות שהייתי צריך להתמודד איתן ואת הפתרונות שלהן.
כאדם, אני תמיד עושה כמיטב יכולתי כדי לעזור לאחרים. במהלך ימי הלימודים והאוניברסיטה, אודיע לחברים שלי נושאים מסוימים אחרי הבנתי את הנושאים האלה בעצמי. ההשתתפות ב-GSoD היא צעד מצוין שמאפשר לי, ככותבת, לתרום לקהילה הזו של קוד פתוח ולהפוך אותה למעניינת ומועילה יותר למשתמשים חדשים ברחבי העולם.