יצירת תיעוד פרויקט באמצעות GitHub Copilot

הושלם

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

תצוגת הצ'אט של GitHub Copilot היא כלי אידיאלי ליצירת תיעוד פרויקט, כי היא יכולה לנתח את כל מבנה הפרויקט ולספק סקירות כלליות ברמה גבוהה של הפרויקט. ניתן להשתמש בתצוגת הצ'אט גם כדי ליצור סוגים ספציפיים של תיעוד, כגון קבצי README, הפניות ל- API ומסמכים אחרים הקשורים לפרוייקט.

אתה יכול להשתמש בכל אחד ממצבי הצ'אט (Ask, Agent או Plan) כדי ליצור תיעוד פרויקט. לכל מצב יש נקודות חוזק וחולשות משלו. מפרטי פרוייקט ואילוצים אחרים משפיעים על המצב שבו יש להשתמש.

חשוב

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

קביעת דרישות תיעוד של פרוייקט

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

לדוגמה, README.md עשויים לכלול את המקטעים הבאים:

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

GitHub Copilot Chat יכול לעזור לך ליצור תיעוד פרויקט שיענה על הצרכים הספציפיים של הפרויקט שלך ושל בעלי העניין שלו.

השתמש במצב Ask agent ליצירת תיעוד פרויקט

מצב סוכן Ask יכול לשמש לניתוח סביבת עבודה ולאחר מכן ליצירת תיעוד.

השתמש בתהליך הבא ליצירת תיעוד פרויקט באמצעות מצב Ask Agent:

1. זהה את דרישות התיעוד ואת המשאבים התומכים.

   • זהה את דרישות התיעוד עבור הפרוייקט שלך. זהה את סוגי התיעוד ואת מקטעי המסמך הדרושים.

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

2. פתח את תצוגת הצ'אט והתחל סשן צ'אט חדש באמצעות מצב Ask Agent.

3. הוסף הקשר להפעלת הצ'אט.

   • ניתן להוסיף הקשר לסשן הצ'אט על ידי גרירה ושחרור קבצים מהתצוגה של Visual Studio Code ב-EXPLORER לתצוגת הצ'אט. אתה גם יכול להשתמש בכפתור 'צורף הקשר' (אייקון מהדק נייר).
   • באפשרותך לפתוח קבצים חיצוניים בעורך הקוד כדי לכלול משאבים שאינם חלק מסביבת העבודה ולהשתמש בהם כדי לספק הקשר נוסף. לדוגמה, אפשר לפתוח קבצי markdown שמכילים הנחיות לתורמים או פרטי קשר ואז להשתמש בכפתור Attach Context כדי להוסיף אותם להקשר של תצוגת הצ'אט.

4. הזן סידרה של בקשות לחקור את דרישות התיעוד שלך.

   אתה יכול להשתמש במצב Ask agent כדי לנתח את מרחב העבודה ולבנות היסטוריית סשן צ'אט שתומכת בדרישות התיעוד שלך. תיאור היעדים שלך יכול לעזור ליצור הקשר עבור הפעלת הצ'אט. שאלת שאלות שמטפלות בדרישות שלך עוזרת GitHub Copilot לזהות את המידע הנדרש ליצירת התיעוד.

   רענן את ההקשר שנוסף לפי הצורך.

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

   לדוגמה: "#codebase /explain I need help creating a README file that can be used in the GitHub repository for this workspace. The file should be formatted as markdown. The README file needs to include the following sections: Project Title, Description, Table of Contents, Installation, Usage, Features, Configuration, and License."

6. סקור את תיעוד הפרוייקט המוצע ומקד את התוצאות באמצעות בקשות חדשות במידת הצורך.

7. העבר את תיעוד הפרוייקט המוצע לקובץ תיעוד של פרוייקט.

   לדוגמה, צור README.md קבצים בבסיס סביבת העבודה והוסף את התוכן המוצע לקובץ.

   אתה יכול להשתמש במצב Ask agent כדי להציע עדכונים לחלקים מסוימים בפרויקט שלך לאחר יצירת המסמך, או להשתמש בכלים GitHub Copilot אחרים שיעזרו בעדכונים.

השתמש במצב התכנון ליצירת תיעוד פרויקט

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

השתמש בתהליך הבא ליצירת תיעוד פרויקט, כגון קובץ README.md, באמצעות מצב התוכנית:

1. זהה את דרישות התיעוד ואת המשאבים התומכים.

2. פתח את תצוגת הצ'אט והתחל סשן צ'אט חדש באמצעות מצב התוכנית.

3. הזן הנחיה שמתארת את משימת התיעוד שלך.

   לדוגמה: "אני צריך ליצור קובץ README ותיעוד תומך לפרויקט הזה. ה-README צריך לכלול: כותרת פרויקט, תיאור, תוכן עניינים, התקנה, שימוש, תכונות, קונפיגורציה ורישיון."

4. בדוק את תוכנית היישום.

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

5. לאחר סיום התוכנית, בחר ב-Start Implementation כדי להעביר את התוכנית למצב סוכן, או בחר Open in Editor כדי לשמור את התוכנית כקובץ Markdown לשימוש עתידי.

   כשאתה בוחר Start Application, GitHub Copilot עובר למצב סוכן ומתחיל ליישם את התיעוד בהתבסס על התוכנית המאושרת. בדוק את קבצי התיעוד שנוצרו וקבל או ביטל את השינויים.

שימוש במצב סוכן ליצירת תיעוד פרוייקט

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

השתמש בתהליך הבא ליצירת תיעוד פרויקט, כגון קובץ README.md, באמצעות מצב סוכן:

1. זהה את דרישות התיעוד ואת המשאבים התומכים.

2. פתח את תצוגת הצ'אט והתחל הפעלת צ'אט חדשה באמצעות מצב הסוכן.

3. הוסף הקשר להפעלת הצ'אט.

   משתתפי הצ'אט אינם זמינים במצב סוכן, ולכן אין באפשרותך לציין @terminal כחלק מהבקשה שלך. עם זאת, באפשרותך להוסיף הקשר להפעלת הצ'אט באמצעות #codebase והוספת קבצים ותיקיות של סביבת עבודה להקשר הצ'אט. ניתן לפתוח קבצים חיצוניים ב-Visual Studio Code ואז להוסיף אותם להקשר הצ'אט באמצעות כפתור Attach Context.

4. הזן בקשה ליצירת תיעוד הפרוייקט המיועד.

   לדוגמה: "צור אוסף של קבצי תיעוד של פרוייקט. צור או עדכן את README.md סביבת העבודה עבור מאגר זה. צור או עדכן את UsageExamples.md הקובץ. צור או עדכן את ChangeLog.md הקובץ. כלול קישורים בין קבצי התיעוד, הכיתות והשיטות של הפניות מקושרות והבטיח עקביות בין המסמכים."

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

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

יכולות מצב סוכן

קיימות כמה משימות תיעוד שבהן מצב סוכן הוא הבחירה הטובה ביותר.

1. יצירת תיעוד מרובה קבצים וחוצה קבצים.

   • מצב סוכן יכול לנתח את מבנה הפרוייקט כולו, לאסוף מידע מקבצים ותיקיות מרובים וליצור תיעוד המקשר לסכם תוכן בכל בסיס הקוד. לדוגמה, יצירת הפניה מלאה ל-API או קובץ README שמתאר את כל הרכיבים העיקריים.

2. ניתוח וסיכום אוטומטיים של פרוייקטים.

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

3. יצירת תוכן דינאמי (לדוגמה, דוגמאות שימוש, טבלאות כיתה)

   • מצב סוכן יכול לסרוק את הפרוייקט כדי ליצור דוגמאות שימוש, טבלאות אחריות כיתה או רשימות של ממשקי API ציבוריים.

4. משימות תיעוד של אצווה.

   • מצב סוכן יכול לבצע רצף של משימות תיעוד (לדוגמה, עדכון README, יצירת קובץ CONTRIBUTING.md, יצירת מסמכי API, עדכון שינויים) בזרימת עבודה אחת.

5. קישור וניווט חכמים.

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

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

תקציר

GitHub Copilot יכול לעזור לך ליצור תיעוד פרויקט שמתאים לצרכים הספציפיים של הפרויקט שלך ושל בעלי העניין בו. תצוגת הצ'אט יכולה לשמש ליצירת תיעוד פרויקט בשלושה מצבים שונים: שאל, סוכן ותכנון. לכל מצב יש נקודות חוזק וחולשות משלו, והמצב הטוב ביותר לשימוש תלוי במשימה הספציפית שלידך. מצב Ask agent הוא הטוב ביותר לשאול שאלות על בסיס הקוד או רעיונות הטכנולוגיה שלך. מצב הסוכן הוא הטוב ביותר ליצירת תיעוד פרויקט שדורש הבנה מעמיקה של הפרויקט. מצב התוכנית הוא הטוב ביותר ליצירת תוכנית יישום מפורטת לפני יצירת תיעוד, שניתן להעביר למצב סוכן לביצוע.