דף זה מכיל את הפרטים של פרויקט כתיבה טכני שהתקבל בעונת Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- BRL-CAD
- כתב טכני:
- sahibkaur
- שם הפרויקט:
- מדריך למתחילים בנושא BRL-CAD
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מדריך למתחילים לריאל ברזילאי (BRL-CAD)
תקציר של הפרויקט
מטרת הפרויקט הזה היא ליצור תיעוד ייעודי למשתמשים שאינם רק חדשים ב-BRL-CAD, אלא גם חדשים בקוד פתוח.
למה דווקא הפרויקט הזה
כשנכנסתי לראשונה לאתר של BRL-CAD, כשהייתי חדש בתחום הקוד הפתוח וה-BRL-CAD, נדהמתי מכמות המידע בבת אחת. אבל לעומק, ידעתי שיש כאן הרבה מה ללמוד. לכן רציתי ליצור תיעוד עבור משתמשים חדשים כמוני כדי להפיק תועלת רבה מהקהילה הזו וכדי שיהיה לי קל להתחיל לעבוד.
שערים
הפרויקט הזה יטרגט משתמשים חדשים. אז אלה כמה נקודות שהמסמכים שלי נועדו להשיג: כדי להבטיח שמשתמשים חדשים מרגישים בנוח: מכיוון שהתיעוד הזה מיועד לא רק למשתמשים חדשים ב-BRL-CAD, אלא גם למשתמשים חדשים בקוד פתוח.
כדי לעשות זאת, א:
- חשוב להקפיד שציון פלש-קינקייד יהיה גבוה מ-50. לפי שיטת פלש-קינקייד, ככל שהניקוד גבוה יותר, כך קל יותר להבין את הקטע. אפשר לבדוק את ציון הקריאות שלו באינטרנט.
- השתמשו ברשימות תבליטים או ברשימות ממוספרות כדי שהקוראים לא ישתעמו או יסיחו את דעתם של אנשים מפסקאות ארוכות.
- כדאי להשתמש בפסקאות ומשפטים קצרים יותר, כי נדרשת חשיבה מחדש יחסית, כדי לקרוא ולהבין משפטים ארוכים יותר.
- אפשר להשתמש בכותרות משנה כדי לחלק את הטקסט לקטגוריות. תיעוד מסודר: יש לתיעוד מובנה תפקיד קריטי בהכוונה של משתמשים חדשים. כך הם לא הולכים לאיבוד, ומציינים לאן הם הולכים ומה הם עושים. לשם כך, בניתי מפת חשיבה כללית שתעזור לנו לתעד את המדריך למתחילים בצורה מאורגנת.
תיאור הפרויקט
הפרויקט הזה מתמקד בכתיבת תיעוד למשתמשים חדשים כדי לעזור להם להשתמש בתוכנה הזו.
הדוגמה הבאה ממחישה איך בכוונתי ליצור תיעוד תיאורי יותר.
מבוא בסיסי: BRL-CAD (מבוטא be-are-el-cad) הוא גיאומטריה יציבה בונה (CSG) עיצוב מוצק בעזרת מחשב (CAD). זוהי מערכת רבת עוצמה, חוצת פלטפורמות וקוד פתוח לבניית מודלים תלת-ממדיים של עיצוב בעזרת מחשב והדמיה גרפית. לא מצליחים למשוך את הראש? ננסה להסביר. קוד פתוח: תוכנת קוד פתוח היא תוכנה עם קוד מקור, שכל אחד יכול לבדוק, לשנות ולשפר. BRL-CAD הוא תוכנת קוד פתוח, שמאפשרת לכם לתרום ולשפר את BRL-CAD יותר מבעבר! תכנון בעזרת מחשב (CAD): במילים פשוטות, CAD הוא שימוש בתוכנות מחשב כדי ליצור ייצוג גרפי דו-ממדי או תלת-ממדי של אובייקטים פיזיקליים. מערכת לבניית מודלים מוצקים: BRL-CAD מתמקדת בבניית מודלים יציבים של CAD. בניית מודל מוצק נבדלת מצורות אחרות של מידול גיאומטרי, בזכות דגש על דיוק פיזי, ועל תיאור מלא של המרחב התלת-ממדי. היא מדמה אובייקט גם באופן פנימי וגם מחוצה לו. גיאומטריה מוצקת בונה (CSG): CSG מאפשר לייצג מודלים מורכבים כסדרה של פעולות בוליאניות בין פרימיטיבים. העצמים המוצקים הפשוטים ביותר שמשמשים לייצוג נקראים פרימיטיבים. כדי להבין את CSG ברמה הבסיסית, אפשר לעיין כאן.
*כפי שצוין בתיאור הרעיון לפרויקט: המסמכים יכסו באופן מינימלי את ההתקנה הבסיסית, תיאור כולל של היכולות, של עקרונות מידול של BRL-CAD, שימוש בסיסי בכלים העיקריים, מידול, ייבוא/ייצוא, ניתוח ועיבוד.
לפניך מבוא קצר לאופן שבו אכסה כל חלק בתיעוד.
- התקנה בסיסית: אני אוסיף מדריך מפורט להתקנת תוכנת BRL-CAD יחד עם צילומי מסך נדרשים. המדריך למתחילים הוא מקום נחמד למשתמשים חדשים. הנה כמה מהדברים החסרים:
- השלבים במדריך למתחילים לא מסומנים ברשימת נקודות או ממוספרים. הוספת מדריך מפורט וצילום מסך בסוף כל שלב מגבירה את הסיכוי שהמשתמשים יתעניינו במדריך.
- תיאור כללי של היכולות: קטע זה מכיל את כל התחומים שבהם BRL-CAD יכול להראות פלאים. גישה דיאגרמטית היא דרך טובה יותר למשוך תשומת לב לחלק הזה.
- עקרונות בניית המודלים של BRL-CAD: בחלק הזה נדרש הסבר נוסף, כי המשתמש יכול להבין טוב יותר את ה-BRL-CAD ברגע שיבין היטב את עקרונות המודל האלה.
- שימוש בסיסי בכלים עיקריים: במסגרת הזו, נלמד מדריכים נפרדים על הכלים העיקריים ועל השימוש הבסיסי בהם. אלה יהיו מדריכים מפורטים.
- ייצוא/ייבוא: המשתמשים יכירו את ספריית ההמרות הגאומטרית. אחד השימושים הנפוצים ביותר ב-BRL-CAD הוא להמיר גיאומטריה מפורמט אחד לפורמט אחר. בסעיף הזה, נדבר על משתמשים שהשלימו המרה וייצוא ייבוא.
- עיבוד: בסרטון נסביר את יסודות הרינדור ואת הצורך בו בתוכנה שלנו. המשתמשים יכירו גם איך לעבד תמונות בריאל ברזילאי (BRL-CAD).
מלבד זאת, אנו מתמקדים גם בנקודות הבאות:
- תחילת התיעוד תכלול הבנה בסיסית של התוכנה הזו.
- איך משתמשים יכולים להתחבר לקהילה הזו בקוד פתוח. קישור לצ'אט של BRL-CAD Zulip.
- ברמה מופשטת, התיעוד קצת הומוריסטי ובקשה מהמשתמשים החדשים לא להרתיע ממילים גדולות. אהבתי את הגישה האמפתית שבה נעשה שימוש בדף הראשי של BRL-CAD wiki.
- יוצגו בו צילומי מסך של כמה מהדברים המדהימים שמשתמשים יכולים לעשות באמצעות התוכנה.
יעדים
יולי (תקופת הבדיקה של ההצעה)
- אכיר את התוכנה ואת מסמכי ה-wiki שלה טוב יותר בזמן שאעבור על המדריכים הקיימים.
- אני אוסיף שיפורים במסמכים הקיימים.
1 באוגוסט – 7 באוגוסט (גיבוש קהילתי)
- דיון עם חונכים על הפרויקט.
- צמצום פרטי הפרויקט.
- מבצעים את השינויים הנדרשים בציוני הדרך (אם צריך).
8 באוגוסט – 14 באוגוסט
- היכרות עם Docsbook 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 בנובמבר
- עבודה על ה-XML של Docsbook
6 בנובמבר עד 12 בנובמבר
- לבקש ביקורות מהחונכים ומחברי הקהילה האחרים, ולעבוד על השינויים.
- דיון עם מנטורים וביצוע שינויים סופיים.
12 בנובמבר עד 22 בנובמבר
- תהליך דיון ושינויים.
- מסירת הפרטים הסופיים לתיעוד.
פרטים עליי
אני עוסקת בכתיבה מאז ימי הלימודים שלי. הייתי חוזר הביתה מבית הספר וכותב על היום שלי; מה שיפר את היום שלי או גרוע יותר. תמיד רציתי לרשום את הטעויות שעשיתי ואיך אוכל לשפר אותן.
במהלך ההכשרה שלי כמעצבת אתרים, התבקשנו לכתוב מה אנחנו לומדים מדי יום. אתעד חלק מהבעיות שנתקלתי בהן ואת הפתרון להן.
כאדם, אני תמיד מתחיל כמיטב יכולתי לעזור לאחרים. בימי בית הספר והמכללה, הייתי מסבירה לחברים שלי כמה נושאים אחרי שהם היו מבינים את הנושאים האלה בעצמי. ההשתתפות ב-GSoD היא צעד נפלא שבעזרתו אני, ככותבת, יכולה לתרום בהפיכת קהילת הקוד הפתוח הזו למרתקת ומועילה יותר למשתמשים חדשים בכל רחבי העולם.