כיצד לפתח מיומנויות תיעוד טכניות במהלך מיקום הקו-אופ שלך

מדוע מיומנויות תיעוד טכניות הן יצירת מקצוע

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

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

המונחים: Observe, Absorb, and Model

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

ביצוע מסמך ביקורת

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

Deconstruct Exemplary Documents

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

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

אתה יכול רק ללמוד כל כך הרבה על ידי התבוננות בסופו של דבר, אתה חייב להרים את העט (או מקלדת) היופי של מיקום קו-אופ הוא כי תיעוד אותנטי צריך בכל מקום; אתה רק צריך להתנדב.

התחל עם סימנים נמוכים

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

קבל בעלות על גדול יותר

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

Embrace Feedback כ- Catalyst for growth

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

יצירת מעגל ביקורת

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

למד דיקי וליישם קריטיב

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

לשלוט בכלים של המסחר

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

שפות משקל קל

(ב) פורמט פנטסטי של LT:0 (MarkdownFLT:1) הוא עכשיו ubiquitous, כוח לקרוא מכונים, wikis, ו גנרטורים באתר סטטיים.קבל מעבר לסודות, למד כיצד ליצור טבלאות, להטמיע תמונות עם כיתובות, לכתוב הודעות טקסט מהיר יותר (הערות, אזהרות), ולהשתמש בבלוקים ממולאים עם זיהוי שפה כדי להדגיש את התוכן האקדמי של 3.

מסמך-כקוד עם Static Site Generator

(הופנה מהדף ⁇ ) , (ה) , עיין במסמכים של חברת טכנולוגיה (Doflu) כקודש (Doex Effect), אשר ניתן לעיין בהוראות ה-Convention) וכן לבחון את כלי ה-FLT:0MkDocssssual FLT:1, FLT:2Docusaurusation of aLT 3, and you can to a brief your site to a use a new your own your own your own your own your own your own your own your own your own your own your own your own your own your service.

בקרת גרסאות ושיתוף פעולה

(התיעוד חי ונושם, במיוחד בסביבות זריזות.למידה להשתמש ב- Git לתיעוד - ביצוע שינויים, כתיבת הודעות בעלות משמעות, פתיחת בקשות, פתרון סכסוכים למיזוג - חשוב בדיוק כמו השימוש בו עבור קוד, הפעלת ענף, ביצוע עדכונים, ובקשת ביקורות מעמיתי צוות שינוי (Trifix) לא רק משפרת את האיכות הטכנית של המסמכים אלא גם בונה את כישורי שיתוף הפעולה שלך רבים של סטודנטים משותפים הם מופתעים כמה שהם לומדים על ידי ביקורת על ידי JF) כמו מעקב אחר כלי ניהול זה.

האנטומיה של תוכן טכני יעיל

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

תוכנית עם הקורא שלך בראש

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

מבנה לSquinability

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

1. פתח את המסוף ונ לנווט למנהל הפרויקט.
2. (ב) ,2 (ב) כדי להתקין את התלויים.
3. העתק את הקובץ (FLT 3: 3) ל-FLT:4 ולהמלא את המפתחות של ה- API שלך.
4. (ב) ,5) כדי להתחיל את השרת המקומי.

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

אחריות והסכמה בשפה

בכתב טכני, מילה חד-משמעית אחת יכולה לגרום שעות של בלבול.להיות ספציפי ללא רחמים במקום לכתוב "התהליך עשוי לקחת קצת זמן", לכתוב "הבנייה בדרך כלל משלימה ב 3-5 דקות על מכונת dev סטנדרטית" במקום "ללחץ על הכפתור", לכתוב "לחץ על המכשיר המלא" שלך, כמו "להציל" את קובץ ה-"מסלול" הראשון שלך, כמו "לה" (FLT)" (FLT) "להחזיק את הקובץ הראשון" (או "להחזיקים") ו" (בפרק אחד) במדריך אחד) שלך, "מכוון" (או" (FLT) במדריך אחד) שלך, "להשתמש) בקובץ אחד בלבד, "להחזיק במדריך פתוח") במדריך אחד בלבד, "להחזיק במדריך אחד בלבד, "מכוון" (או" (או" (FLT 1) שלך) שלך) שלך, כמו "להחזיק במדריך אחד) ו" (מכוון" (או "מרוץ אחד) במדריך אחד בלבד, לדוגמה, "להחזיק במדריך פתוח) במדריך אחד, "להחזיק במדריך אחד בלבד, "להחזיק במדריך אחד בלבד) במדריך אחד בלבד, "להחזיק במדריך אחד בלבד,

ויזואלים שגורמים להם לא לטרוף

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

סוגי המסמכים הנפוצים שאתם יכולים

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

מדריך למשתמש ו Tutorials

(המסמכים האלה הולכים למשתמש באמצעות סדרה של צעדים להשגת מטרה.התחל עם הצהרה ברורה: "על ידי סוף המדריך הזה, אתה תפעיל יישום אינטרנט פשוט על הפלטפורמה הפנימית שלנו" לשבור את הדרכות לתוך נתחים ניתנים לניהול, כל אחד עם תוצאות הלמידה שלו עצמו.לאחר הצעד האחרון, לספק סעיף "צעדים ספציפיים" המקשר לנושאים מתקדמים יותר באמפתיה; נסה את השלבים בעצמך על מכשיר לימוד חדש ללא ספק, אם אתה מקבל מענה על ידי Windows: "צעדים" (F) ללא ספק, אם אתה מקבל תמיכה ב-" (Dip) ללא שינוי ב-" (D) ו-" (Dip) הוא מ-" 7) ללא ספק, אם אתה מקבל גישה ל-" (T) מ-" (T) הוא מוסיף, אם אתה מקבל יותר ויותר LT) מ-"מספק פרק 7) עם כל אחד מהם, אם אתה מקבל גישה ל-T) שקישורים נוספים, אם אתה מקבל גישה ל-" (D) שקישורים ל-" (D) שקישורים ל-" (D) שקישורים ל-"שלבים ל-"שלבים ל-"שלבים להנחיות ל-"שלבים ל-"שלבים ל-"שלבים ל-"

מסמך API

אם אתה עובד עם מערכות אחוריות או אינטגרציה, תיעוד API עשוי להפוך ללחם שלך וחמאה. ⁇ API טוב להסביר לא רק מה גורם קצה עושה, אלא גם שיטת האימות, לבקש פרמטרים, תגובה schemas, קודים שגיאה, ומגבלות קצב.תמיד כוללים בקשות ותשובות - רצוי שניתן להעתיק ולהדביק ישירות לתוך כלי כמו Postman או cURL כלים כמו אור או להפסיק לקרוא גירסאות.

מסמך פנימי

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

אתגרים משותפים

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

תסמונת בלוק ואימפולסיסטר

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

התמודדות עם מסמכים חיצוניים או לא קיימים

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

מחיקת מסמכים עם אחריות אחרת

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

בניית תיק מסמכים ופגיעה בהשפעה

בעוד ש-Co-op שלך מתנדנד, לחזק את העבודה שלך לנכס מוחשי.ג'ר את המסמכים שיצרת או השתפרו באופן משמעותי - באישור המעסיק שלך, כמובן - ואנונימיות או לתקן כל מידע קנייני. צור אתר פשוט PDF או אתר אישי (באמצעות GitHub Pages, לדוגמה) המציג את החלקים הטובים ביותר שלך עם תיאורים קצרים של ההקשר וההשפעה שלך אם עדכון שלך על גבי לוח זמנים חדש עשוי להיות מתואם, כלומר, כלומר, למעט כמה ימים מתאימים, כולל משוב מיידי, כולל, כלומר, כלומר, כלומר, כלומר, כולל שיפור מיידי של קובץ תמיכה, כולל, כולל, כולל, כלומר, כלומר, כולל שיפור מיידי של קובץ תמיכה של קובץ תמיכה של קובץ תמיכה.

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

המשך המסע מעבר לקו-אופ

מיקום ה-Co-op שלך הוא ה-FLT, לא היעד.לאחר שהמונח מסתיים, הישארו מעורבים בקהילת הכתיבה הטכנית.הצטרפו ל-FLT:0Write The Docs Slackphs SlackFLT:1 כדי להתחבר עם אלפי מעדינים, לחלוק טיפים, פרסום עבודה ועידוד, שקול לקרוא ספרים כמו "Docs for Developers" על ידי ג'ארד באט אל, אשר מספק מסגרת מקיפה עבור ניהול קוד פתוח, אפילו, אם אתה יוצר את אותו מנהל שירות, או מנהל שירות טוב יותר, אם אתה יודעי, אם אתה יודע, ישמור, ישמור, או מנהל שירות, ישמור, אם אתה יודע, ישמור, ישמור, או מנהל שירות טוב יותר טוב יותר, או מדריך, אם אתה יכול לעשות את אותו טוב יותר, אם אתה יכול לעשות את אותו עובד, או מנהל שירות טוב יותר, אם אתה יכול לעשות את אותו מנהל שירות טוב יותר, אם אתה יכול להיות בעל שם, אם אתה יכול לעשות את אותו עובד, אם אתה יכול להיות בעל שם, אם אתה יכול להיות בעל שם, אם אתה יכול לעשות שימוש טוב יותר, אם אתה יכול לעשות את זה יהיה, אם אתה יכול לעשות את זה, ישמור, ישמור, ישמור, ישמור, אם אתה יכול לעשות את

כדי לשמור על הכישורים שלך חד, להתנדב לכתוב תיעוד עבור פרויקטים קוד פתוח.פרוייקטים רבים על GitHub יש תווית 9 עבור משימות תיעוד. Contributing פרויקטים כגון תגובה, Vue, או FLT:0Django ProjectFLT 9 יכול לספק ניסיון מגוון ולבנות את תיק האינטרנט שלך.

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