🥇השתמש ב-GIT לתיעוד

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

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

הצהרת הבעיה

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

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

לפני 10 שנים הגישה הייתה פשוטה: היינו יוצרים מסמך או מסמכי MS Word ואיכשהו מארגנים את עבודת השינוי.

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

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

מהנדס מוריד את הגרסה העדכנית ביותר של מסמך MS Word (.docx).

משנה שם

עושה שינויים כדי לעקוב אחר אופנה

שולח את המסמך עם עריכות לאדריכל

שולח גם רשימה של כל התיקונים עם הערות

אדריכל מנתח שינויים

אם הכל בסדר, הוא מעתיק את השינויים האלה לקובץ עם הגרסה האחרונה, משנה את הגרסה ומעלה אותו למשאב משותף

אם יש הערות, נפתח דיון (אימייל או פגישות)

מושגת הסכמה

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

גיט, מרקדאון

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

Git הוא כלי פיתוח. אבל למה לא להשתמש בו לתהליך התיעוד? במקרה זה, הבעיה של עבודה מרובה משתמשים נפתרת. אבל כדי לנצל את מלוא היכולות של Git, אנחנו צריכים פורמט מסמך טקסט, אנחנו צריכים למצוא כלי אחר מלבד MS Word, ו-Markdown מעולה למטרות אלו.

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

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

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

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

עקב אי-זהות הפונקציונליות של MS Word ו-Markdown, אי אפשר לפתור בעיה זו באופן כללי, לדעתי, אך האם ניתן לעשות זאת ביחס למצבים ספציפיים, דרישות ספציפיות? הניסיון שלי הראה שכן, זה אפשרי וסביר להניח שזה אפשרי עבור הרבה, או אולי אפילו רוב המצבים.

פתרון של בעיה מסוימת

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

הוסף שדות ל-Word עם מספור אוטומטי של כותרות (כתוביות) של טבלאות ותמונות
לשנות סגנון שולחן

לא מצאתי כיצד לעשות זאת באמצעות תקן (Pandoc) או אמצעים ידועים. אז יישמתי את הסקריפט python עם pywin32 חֲבִילָה. כתוצאה מכך, קיבלתי אוטומציה מלאה. כעת אני יכול להמיר את קובץ ה-Markdown שלי לטופס מסמך MS Word הרצוי בפקודה אחת.

ראה פרטים כאן.

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

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

נוסחה קצרה לגישה זו:

Markdown + Git -- (нечто) --> MS Word

זה לא משנה מה זה "משהו". במקרה שלי זה היה Pandoc ו-python עם pywin32. ההעדפות שלך עשויות להיות שונות, אבל הדבר החשוב הוא שזה אפשרי. וזהו המסר העיקרי של המאמר הזה.

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

תהליך

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

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

נסתכל על תהליך פשוט המבוסס על "זרימת github". את התיאור שלו ניתן למצוא הן באינטרנט והן באתר יש.

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

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

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

מה היתרון של גישה זו לעומת, למשל, התהליך המתואר בדוגמה לעיל?

למעשה, התהליכים די דומים, פשוט החלפתם

העתקת קובץ -> יצירת ענף
העתקת טקסט לקובץ הסופי -> מיזוג
העתקת השינויים האחרונים לעצמך -> git pull/fetch
דיון בהתכתבות -> בקשות למשוך
מצב מעקב -> git diff
הגרסה האחרונה שאושרה -> סניף מאסטר
גיבוי (העתקה לשרת מרוחק) -> git push
...

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

ברמה גבוהה יותר זה מאפשר לך

ליצור תהליך ברור, פשוט ומבוקר לשינויים במסמכים
כי אתה יוצר את המסמך הסופי (בדוגמה שלנו MS Word) באופן אוטומטי, זה מקטין את הסבירות לשגיאות עיצוב

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

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

איך עוברים לתהליך חדש?

בתחילת המאמר כתבתי שמחר אפשר להתחיל לעבוד בצורה חדשה. איך לקחת את העבודה שלך לכיוון חדש?

להלן רצף השלבים שסביר להניח שתצטרך לבצע:

אם המסמך שלך גדול מאוד, פצל אותו לחלקים
המר כל חלק ל-Markdown (באמצעות Pandoc למשל)
התקן את אחד מעורכי Markdown (אני משתמש Typora)
סביר להניח שתצטרך להתאים את העיצוב של מסמכי Markdown שנוצרו
התחל ליישם את התהליך המתואר בפרק הקודם
במקביל, התחל לשנות את סקריפט ההמרה כך שיתאים למשימה שלך (או צור משהו משלך)

אינך צריך לחכות עד שיצרת ותשכלל את מנגנון ההמרה של Markdwon -> סוג הפלט הנדרש של מסמך. הנקודה היא שגם אם אינך מסוגל להפוך במהירות מלאה להליך המרת קבצי ה-Markdown שלך, אתה עדיין יכול לעשות זאת בצורה כלשהי באמצעות Pandoc ואז להביא אותו לטופס הסופי באופן ידני. בדרך כלל לא צריך לעשות זאת לעתים קרובות, אלא רק בסוף שלבים מסוימים, והעבודה הידנית הזו, למרות שאינה נוחה, עדיין, לדעתי, די מקובלת בשלב איתור הבאגים ולא אמורה "להאט" את התהליך הַרבֵּה.

כל השאר (Markdown, Git, Pandoc, Typora) כבר מוכן ולא דורש הרבה מאמץ או זמן כדי להתחיל לעבוד איתם.

מקור: www.habr.com