דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- ריאל ברזילאי (BRL)
- כתב טכני:
- סאהיבקאר
- שם הפרויקט:
- מדריך למתחילים ל-BRL-CAD
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מדריך למתחילים ל-BRL-CAD
תקציר פרויקט
מטרת הפרויקט הזה היא ליצור תיעוד הייעודי למשתמשים שלא רק מתחילים להשתמש ב-BRL-CAD אלא גם חדשים בתחום הקוד הפתוח.
למה דווקא הפרויקט הזה?
בפעם הראשונה שביקרתי באתר של BRL-CAD, השתמשתי בידע של הקוד הפתוח ו-BRL-CAD, והתחמקתי מכמות המידע בבת אחת. אבל אחרי הכל, עמוק בפנים, ידעתי שיש כאן עוד הרבה מה ללמוד. לכן רציתי ליצור תיעוד עבור משתמשים חדשים כמוני כדי להפיק הרבה מהקהילה הזו ולהרגיש בנוח להתחיל איתה.
שערים
הפרויקט הזה יטרגט משתמשים חדשים. אז הנה כמה נקודות שהמסמכים שלי נועדו להשיג: כדי להבטיח שמשתמשים חדשים ירגישו בנוח: מכיוון שהתיעוד הזה מיועד למשתמשים חדשים לא רק משתמשים חדשים ב-BRL-CAD אלא גם למשתמשים חדשים בקוד פתוח.
כדי להשיג את המטרה הזו, א:
- יש לוודא שציון פלש-קינקייד של המסמך צריך להיות לפחות 50. לפי שיטת פלש-קינקייד, ככל שהניקוד גבוה יותר, כך קל יותר להבין את הקטע. אפשר לבדוק את ציון הקריאוּת שלו באינטרנט.
- השתמשו ברשימות תבליטים או ברשימות ממוספרות כדי שהקוראים לא ישתעממו או יסיחו את דעתם של הקוראים.
- כדאי להשתמש בפסקאות ומשפטים קצרים יותר, כי נדרשת עבודת חשיבה יחסית כדי לקרוא ולהבין משפטים ארוכים.
- להשתמש בכותרות משנה כדי להפריד בין חלקי הטקסט. תיעוד מסודר: חשוב לשמור על תיעוד מסודר כדי לעודד משתמשים חדשים. כך הם לא הולכים לאיבוד, ומציינים לאן הם הולכים ומה הם עושים. לשם כך, יצרתי מפת חשיבה כללית שתעזור לנו לתעד את המדריך למתחילים בצורה מאורגנת.
תיאור הפרויקט
הפרויקט הזה מתמקד בכתיבת תיעוד למשתמשים חדשים כדי לעזור להם להשתמש בתוכנה הזו.
לפניכם דוגמה לאופן שבו בכוונתי ליצור תיעוד תיאורי יותר.
מבוא בסיסי: BRL-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.
- ברמה המופשטת, כדאי שהתיעוד יהיה קצת הומוריסטי ושיתבקשו מהמשתמשים החדשים לא להירתע משימוש במילים גדולות. אהבתי את הגישה האמפתית שבה נעשה שימוש בדף הראשי של wiki של ה-BRL-CAD.
- יוצגו בו צילומי מסך של כמה דברים מדהימים שהמשתמשים יכולים לעשות באמצעות התוכנה הזו.
אבני דרך
יולי (תקופת בדיקת ההצעה)
- אכיר טוב יותר את התוכנה ואת מסמכי ה-wiki שלה בזמן שאעבור על המדריכים הקיימים.
- אני רוצה לשפר את המסמכים הקיימים.
1 באוגוסט עד 7 באוגוסט (שיתוף פעולה בקהילה)
- דיונים עם מנטורים על הפרויקט.
- צמצום פרטי הפרויקט.
- מבצעים את השינויים הנדרשים באבני הדרך (אם צריך).
8 באוגוסט – 14 באוגוסט
- הסבר על Docsbook XML
15 באוגוסט – 21 באוגוסט
- כתיבת מסמכים עבור "Basic Introduction to 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 היא צעד נפלא שבו אני, ככותבת, יכולה לתרום בהפיכת קהילת הקוד הפתוח הזו למעניינת ומועילה יותר למשתמשים חדשים בכל העולם.