כיצד לכתוב מסמך טוב לעיצוב תוכנה

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

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

המאמר מחולק לארבעה חלקים:

  • למה לכתוב מסמך עיצוב
  • מה לכלול במסמך עיצוב
  • איך כותבים את זה
  • התהליך סביבו

מדוע לכתוב מסמך עיצוב?

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

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

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

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

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

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

מה לכלול במסמך עיצוב?

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

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

כותרת ואנשים

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

סקירה כללית

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

הֶקשֵׁר

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

יעדים ולא יעדים

על סעיף היעדים:

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

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

אבני דרך

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

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

Start Date: June 7, 2018

Milestone 1 — New system MVP running in dark-mode: June 28, 2018

Milestone 2 - Retire old system: July 4th, 2018

End Date: Add feature X, Y, Z to new system: July 14th, 2018

הוסף [Update]כאן סעיף משנה אם ה- ETA של כמה מאבני דרך אלה ישתנה, כך שבעלי העניין יוכלו לראות בקלות את האומדנים המעודכנים ביותר.

פיתרון קיים

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

המשתמשכַּתָבָהזו דרך נהדרת למסגר זאת. זכור כי במערכת שלך עשויים להיות סוגים שונים של משתמשים עם מקרי שימוש שונים.

פיתרון מוצע

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

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

פתרונות חלופיים

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

יכולת בדיקה, ניטור והתראה

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

השפעה חוצה צוותים

איך זה יגדיל את נטל השיחות והמכשיר?

כמה כסף זה יעלה?

האם זה גורם לרגרסיה של חביון למערכת?

האם הוא חושף פגיעות אבטחה כלשהן?

מהן השלכות ותופעות לוואי שליליות?

כיצד יכול צוות התמיכה להעביר זאת ללקוחות?

שאלות פתוחות

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

סקופ וציר זמן מפורט

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

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

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

איך כותבים את זה

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

כתוב בפשטות ככל האפשר

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

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

הוסף הרבה תרשימים ודיאגרמות

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

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

כלול מספרים

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

נסו להצחיק

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

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

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

ערכו את הבדיקה הספקנית

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

ערכו את מבחן החופשה

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

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

תהליך

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

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

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

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

  1. בקש מהנדס מנוסה או מוביל טכנולוגי בצוות שלך להיות הסוקר שלך. באופן אידיאלי זה יהיה מישהו שמכובד היטב ו / או מכיר את מקרי הבעיה. שוחד אותם עם בובה במידת הצורך.
  2. היכנס לחדר ישיבות עם לוח לבן.
  3. תאר את הבעיה שאתה מתמודד עם המהנדס הזה (זהו צעד חשוב מאוד, אל תדלג עליו!).
  4. ואז הסבירו את היישום שעומד בראשכם, ושכנעו אותם שזה הדבר הנכון לבנות.

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

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

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

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

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

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

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

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

לסיום, בואו נקבל מטא ממש לרגע: איך נעריך את ההצלחה של דוק עיצוב?

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

  1. אתה מבלה 5 ימים בכתיבת מסמך העיצוב, זה מכריח אותך לחשוב על חלקים שונים בארכיטקטורה הטכנית
  2. אתה מקבל משוב ממבקרים Xשהוא החלק המסוכן ביותר בארכיטקטורה המוצעת
  3. אתה מחליט ליישם Xתחילה כדי להסיר את הסיכון לפרויקט
  4. כעבור 3 ימים אתה מבין שזה Xלא אפשרי, או הרבה יותר קשה ממה שהתכוונת במקור
  5. אתה מחליט להפסיק לעבוד על הפרויקט הזה ולתעדף במקום עבודה אחרת

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

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

נתתי אשראי במקום בו מגיע האשראי, למדתי הרבה מהאמור לעיל בעבודה לצד כמה מהנדסים מדהימים ב- Plaid (אנחנו עובדים! בואו לעצב ולבנות איתנו כמה מערכות טכניות מתוקות) ו- Quora.

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