טיפים לכתיבה טכנית שמשאירה רושם טוב

אם אתם כותבים משהו שהמטרה שלו להשאיר על הקוראים שלכם

רושם ש"הבן אדם הזה יודע על מה הוא מדבר" -

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

או אפילו קובץ readme ליד פרויקט שאתם מצרפים לקורות חיים -

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

במיוחד אם אתם באמת אנשים שיודעים על מה אתם מדברים.

 

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

 

היו ספציפיים

 

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

 

הכותרות הבאות הן דוגמאות טובות לפוסטים ממוקדים:

  1. איך עובד Find My iPhone כשהאייפון כבוי
  2. מה חדש בריאקט 18
  3. איך פרצנו אלפי חשבונות Azure
  4. איך לבנות אינטגרציה בין Airflow ל lakeFS
  5. ה Git Aliases האהובים עליי

 

לעומתן עם הכותרות הבאות הרבה יותר קשה להשאיר רושם טוב:

  1. איך לפרוץ ל APIs ב 2021
  2. מבוא ל Deep Learning
  3. מדריך מקיף על Airflow
  4. האלמנטים של גיט
  5. הכל על אימות זהות והרשאות גישה

 

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

 

 

 

עשו את הקריאה

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

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

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

 

 

עריכה, עריכה ועריכה

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

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

 

בדוגמה מפוסט שפרסמתי אתמול, קוד bash הזה:

#!/bin/bash
for f in [0-9][0-9]*
do
  number=${f%%-*}
  mv "$f" $(printf "%02d-${f#*-}" $((number + 1)))
done

 

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

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

ורק כשהמשכתי להריץ את הדוגמה על עוד ועוד מקרים מצאתי את הבעיה.

 

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

לכתוב על נושא ממוקד ולוודא שכל מה שכתבתם הוא מדויק ומטפל בכל המקרים,

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

 

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

שימו לב כשאתם כותבים לקרוא הרבה קודם, להיות מדויקים ולהיות קשובים להערות הקוראים כדי להמשיך ולשפר.

 

 

https://www.tocode.co.il/