כתיבה טכנית למפתחים

HTML, CSS, JavaScript, Python, PHP, C++, Dart - יש כל כך הרבה שפות תכנות בחוץ ואולי אפילו שולטים בכמה מהן! אבל ככל שאנו שואפים לכתוב יותר קוד טוב יותר, הדרך בה אנו כותבים ומתקשרים בשפה היומיומית הופכת חשובה יותר ויותר... ואולי אפילו מתעלמת ממנה.

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

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

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

כתיבה טכנית נמצאת בכל מקום

בשנה שעברה, הצוות מאחורי הלקוח הפופולרי של Mac Git, Tower, סקר יותר מ-4,000 מפתחים וגילו שכמעט 50% מהם השקיעו בין 3-6 שעות ביום בכתיבת קוד.

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

זה עשוי לכלול:

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

כמובן, תמיד יש זמן להפסקות לשירותים וגם ל-Wordle.

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

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

זה כתיבה טכנית 101.

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

מהו דקדוק טוב?

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

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

תן לי לתת לך סקירה מהירה על השפה.

התחביר האנגלי

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

מילים הן אבני הבניין של האנגלית, והן מתחלקות לשמונה דליים:

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

קול וטון

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

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

1. אני אוהב תכנות.
2. I כמו תִכנוּת! :)

קל לבלבל בין קול לטון, ולהיפך.

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

אותה הודעה, כתובה בשני קולות שונים:

• כֵּיף: "הרחב את הרשת החברתית שלך והישאר מעודכן במה המגמה כעת."
• רְצִינִי: "מצא משרות באחת מאפליקציות הרשתות החברתיות הגדולות ביותר ושוק העבודה המקוון."

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

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

קול אקטיבי ופסיבי

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

השחקן מגיע ראשון ב קול פעיל. לדוגמה: "CSS מצייר את הרקע."

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

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

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

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

הימנעות מטעויות

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

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

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

כתיבת הערות קוד

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

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

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

במקום זאת, השתמש בהערות המספקות מידע נוסף:

red *= 1.2 // Apply a 'reddish' effect to the image

הכל עניין של הקשר. "איזו סוג של תוכנית אני בונה?" זה בדיוק סוג השאלות שאתה צריך לשאול את עצמך.

הערות צריכות להוסיף ערך

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

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

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

הערות צריכות לשקף את הקוד הנוכחי

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

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

cities = sortWords(cities) // sort cities from A to Z

אז דייוויד מבין ש sortWords() למעשה ממיין רשימות מ-Z ל-A. זו לא בעיה, מכיוון שהוא יכול פשוט להפוך את הפלט:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

לרוע המזל, דיוויד לא עדכן את הערת הקוד שלו.

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

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

זה כלל אחד פשוט שיחסוך לך ולצוות שלך הרבה חוב טכני.

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

הערות צריכות להסביר קוד אודיומטי

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

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

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

הערות יכולות לזהות משימות עתידיות

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

// TODO: use a more efficient algorithm
linearSort(ids)

בדרך זו, אתה יכול להישאר ממוקד בזרימה שלך. ובמועד מאוחר יותר, אתה (או מישהו אחר) יכול לחזור ולתקן את זה.

הערות יכולות לקשר חזרה למקור

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

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

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

כתיבת בקשות משיכה

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

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

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

הימנע מעורפל PR כותרות

נא להימנע מכותרות שנראות כך:

• תקן את המבנה.
• תקן באג.
• הוסף תיקון.

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

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

הנה כמה דוגמאות טובות:

• תמכו בתכונות srcset מותאמות אישית ב-NgOptimizedImage
• ברירת המחדל של תצורת תמונה ל-75% איכות תמונה
• הוסף בוררים מפורשים עבור כל ה-ControlValueAccessors המובנים

הימנע ארוך PRs

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

במקום זאת, תוכל:

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

זה לא הרבה יותר נקי עכשיו?

ספק פרטים ב PR גוּף

בניגוד ל PR כותרת, הגוף הוא מה היא מקום לכל הפרטים, כולל:

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

דיווח על באגים

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

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

לדוגמה, רוב הפרויקטים הגדולים מגיעים עם תקיה:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

אסוף צילומי מסך

צלם את הבעיה באמצעות שלך כלי השירות לצילום מסך של המערכת.

אם זה צילום מסך של א CLI תוכנית, ודא שהטקסט ברור. אם זה א UI תוכנית, ודא שצילום המסך לוכד את האלמנטים והמצבים הנכונים.

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

איך לשחזר את הבעיה

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

הנה דוגמה:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

הצע סיבה

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

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

תקשורת עם לקוחות

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

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

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

שאל את השאלות הנכונות

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

• מי קהל היעד שלך?
• מה מטרת האתר?
• מי המתחרה הקרוב ביותר שלך ומה הוא עושה נכון?

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

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

שאלות הרבה יותר תמימות ומקדמות סקרנות על פני איבה.

למכור את עצמך

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

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

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

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

כתיבת מיקרועותק

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

זו אולי הסיבה שאנו רואים לפעמים שגיאות כמו זו:

Error: Unexpected input (Code 693)

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

הימנע מז'רגון טכני

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

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

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

לעולם אל תאשים את המשתמש

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

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

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

אל תציף את המשתמש

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

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

Mailchimp אומר את זה טוב:

[ד]אל תצא מגדרו כדי לעשות בדיחה - הומור מאולץ יכול להיות גרוע יותר מכלום. אם אתה לא בטוח, שמור על פנים ישרות.

(הדגש שלי)

כתיבת סימון נגיש

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

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

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

דברים כמו:

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

סיכום

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

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

משאבי כתיבה טכניים

אם אתה מעוניין בכתיבה טכנית:

אם אתה מעוניין בקופירייטינג:

אם אתה מעוניין במיקרוקופי:

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

אם אתה מעוניין לכתוב למען נגישות: