การเขียนทางเทคนิคสำหรับนักพัฒนา

HTML, CSS, JavaScript, Python, PHP, C++, Dart — มีภาษาโปรแกรมมากมายเหลือเกิน และคุณอาจจะใช้ภาษาเหล่านี้ได้อย่างคล่องแคล่วทีเดียว! แต่ในขณะที่เราตั้งเป้าที่จะเขียนโค้ดให้ดีขึ้นเรื่อยๆ วิธีที่เราเขียนและสื่อสารในภาษาในชีวิตประจำวันก็มีความสำคัญมากขึ้นเรื่อยๆ...และอาจถูกมองข้ามไปด้วยซ้ำ

วิธีที่เราเขียนเกี่ยวกับและรอบๆ โค้ดนั้นมีความสำคัญพอๆ กับตัวโค้ดเอง และถึงแม้คุณจะอยู่ตรงจุดไหน เราทุกคนต่างเห็นพ้องต้องกันว่าคำพูดของเรามีศักยภาพที่จะทั้งช่วยเหลือและทำลายประสิทธิภาพของโค้ด

ในบทความนี้ ฉันต้องการสรุปว่าทั้งสองสาขาที่ดูเหมือนจะแตกต่างกัน — การเขียนโปรแกรมและการเขียน — สามารถมารวมกันและนำทักษะนักพัฒนาของเราไปสู่ระดับต่อไปได้อย่างไร

เดี๋ยวนะ การเขียนทางเทคนิค? ใช่นั่นคือสิ่งที่ฉันหมายถึง ฉันเชื่ออย่างแท้จริงว่าเราทุกคนเป็นนักเขียนในแง่หนึ่งหรืออีกนัยหนึ่ง และฉันมาที่นี่เพื่อให้คำแนะนำเบื้องต้นเกี่ยวกับการเขียน คำแนะนำ และตัวอย่างที่จะช่วยให้คุณเป็นทั้งนักพัฒนาและนักสื่อสารที่ดีขึ้นได้อย่างไร

เทคนิคเขียนได้ทุกที่

ปีที่แล้ว ทีมงานเบื้องหลังไคลเอนต์ Mac Git ยอดนิยมอย่าง Tower สำรวจนักพัฒนามากกว่า 4,000 คน และพบว่าเกือบ 50% ของพวกเขาใช้เวลาระหว่าง 3-6 ชั่วโมงต่อวันในการเขียนโค้ด

และใช่ นั่นคือการสำรวจหนึ่งที่สำรวจกลุ่มเฉพาะที่ค่อนข้างสวย แต่ฉันจินตนาการว่าพวกเราหลายคนตกอยู่ที่ใดที่หนึ่งในช่วงนั้น ไม่ว่ากรณีใด นักพัฒนาซอฟต์แวร์ไม่ได้เขียนโค้ดตลอด 24 ชั่วโมงทุกวัน เพราะตามที่โพลนี้แนะนำ เรากำลังใช้เวลามากมายไปกับการทำอย่างอื่น

ซึ่งอาจรวมถึง:

• การสาธิตคุณลักษณะใหม่
• การบันทึกคุณสมบัติใหม่นั้น
• อัปเดตตั๋วงานที่เกี่ยวข้องกับคุณสมบัติใหม่นั้นหรือ
• งานค้างเพื่อรองรับคุณสมบัติใหม่นั้น

แน่นอนว่ายังมีเวลาพักเข้าห้องน้ำและ Wordle ก็เช่นกัน

อย่างไรก็ตาม สิ่งที่เราทำโดยทั่วไปมักเกี่ยวข้องกับการสื่อสารกับผู้คน เช่น ทีมของคุณ เพื่อนร่วมงาน ลูกค้า ผู้ใช้ และนักพัฒนารายอื่นๆ

ดังนั้นเราจึงใช้เวลาส่วนใหญ่ในการสื่อสารกับมนุษย์ผ่าน คำ นอกจากการสื่อสารที่เรามีกับคอมพิวเตอร์ผ่าน รหัส. คำเป็นภาษาเขียน และถ้าเราเขียนคำพูดได้ดีขึ้น เราก็จะสื่อสารได้ดีขึ้น เมื่อเราสื่อสารได้ดีขึ้น เราก็มักจะได้สิ่งที่ต้องการมากขึ้น

นั่นคือการเขียนเชิงเทคนิค 101

และยังไม่จบเพียงแค่นี้.. โปรแกรมเมอร์บางคนชอบทำผลิตภัณฑ์ของตัวเอง ซึ่งหมายความว่าพวกเขาจำเป็นต้องทำให้การตลาดเป็นส่วนหนึ่งของงาน การเขียนทางเทคนิคก็มีบทบาทอย่างมากเช่นกัน ดังนั้นใช่ ฉันคิดว่ามันค่อนข้างยุติธรรมที่จะพูดว่าการเขียนเชิงเทคนิคคือ จริง ทุกที่.

ไวยากรณ์ที่ดีคืออะไร?

ด้วยภาษาโปรแกรมมากมาย สิ่งสุดท้ายที่เราต้องการคือการเรียนรู้ภาษาอื่น

ไวยากรณ์ เป็นส่วนสำคัญของภาษาอังกฤษ และช่วยปลดล็อกศักยภาพในการสื่อสารได้อย่างเต็มที่ มันทำให้เราเป็นทางการ เป็นมืออาชีพ และสอดคล้องกันมากขึ้น

ผมขอสรุปสั้นๆ เกี่ยวกับภาษา

ไวยากรณ์ภาษาอังกฤษ

เช่นเดียวกับภาษาโปรแกรม ภาษาอังกฤษมีรูปแบบที่ชัดเจนและเริ่มต้นด้วยคำ

คำเป็นส่วนประกอบสำคัญของภาษาอังกฤษและแบ่งออกเป็นแปดกลุ่ม:

คิดถึงพวกนี้จัง UI ส่วนประกอบ: เป็นชิ้นส่วนแบบแยกส่วนที่คุณสามารถเคลื่อนไปมาเพื่อสร้างประโยคที่สมบูรณ์และแข็งแกร่งได้ เช่นเดียวกับที่คุณอาจประกอบเข้าด้วยกันเป็นประโยคที่สมบูรณ์และแข็งแกร่ง UI. ส่วนประกอบทั้งหมดจำเป็นต้องมีอยู่ตลอดเวลาหรือไม่? ไม่แน่นอน! ประกอบประโยคด้วยชิ้นส่วนต่างๆ ที่คุณต้องการเพื่อทำให้ประสบการณ์เสร็จสมบูรณ์ เช่นเดียวกับที่คุณทำกับอินเทอร์เฟซ

น้ำเสียงและโทน

คำศัพท์ เครื่องหมายวรรคตอน โครงสร้างประโยค และการเลือกคำ ทั้งหมดนี้เป็นส่วนผสมของภาษาอังกฤษ เราใช้สิ่งเหล่านี้เพื่อแบ่งปันความคิด สื่อสารกับเพื่อนและครอบครัวของเรา และส่งอีเมลถึงเพื่อนร่วมงานของเรา

แต่สิ่งสำคัญคือต้องพิจารณา เสียง ของข้อความของเรา อัศเจรีย์หนึ่งตัวสามารถเปลี่ยนโทนของข้อความได้อย่างน่าอัศจรรย์ได้อย่างไร:

1. ฉันชอบการเขียนโปรแกรม
2. I กดไลก์ การเขียนโปรแกรม! :)

ง่ายต่อการสับสนระหว่างเสียงกับน้ำเสียง และในทางกลับกัน

เสียงพูด คือสิ่งที่เกี่ยวข้องกับการเลือกคำของเรา ซึ่งขึ้นอยู่กับบริบท ตัวอย่างเช่น บทช่วยสอนสำหรับผู้เริ่มต้นมีแนวโน้มที่จะใช้คำสแลงและภาษาที่ไม่เป็นทางการเพื่อถ่ายทอดเสียงที่เป็นมิตร ในขณะที่เอกสารอาจเขียนในลักษณะที่เป็นทางการ จริงจัง และเป็นมืออาชีพเพื่อพยายามให้ตรงประเด็น

ข้อความเดียวกันเขียนด้วยสองเสียงที่แตกต่างกัน:

• สนุก: “ขยายเครือข่ายโซเชียลของคุณและรับข่าวสารล่าสุดเกี่ยวกับสิ่งที่กำลังมาแรงในตอนนี้”
• จริงจัง: “หางานในแอพเครือข่ายสังคมที่ใหญ่ที่สุดแห่งหนึ่งและตลาดงานออนไลน์”

ไม่ใช่เรื่องผิดปกติที่จะเขียนข้อความโดยไม่ได้ตั้งใจซึ่งมองว่าเป็นการดูหมิ่น ก้าวร้าว และไม่เป็นมืออาชีพ นี่คือที่ โทน เข้ามาเล่น อ่านข้อความของคุณออกมาดัง ๆให้คนอื่นอ่านให้คุณ และทดลองกับเครื่องหมายวรรคตอนและโครงสร้างประโยคของคุณ นั่นคือวิธีที่คุณปรับโทนเสียงของคุณ

นี่เป็นวิธีคิดอีกอย่างหนึ่ง: เสียงของคุณไม่เคยเปลี่ยน แต่น้ำเสียงของคุณเปลี่ยน เสียงของคุณคล้ายกับตัวตนของคุณ ในขณะที่น้ำเสียงเป็นวิธีที่คุณตอบสนองในสถานการณ์ที่กำหนด

เสียงที่ใช้งานและ passive

ประโยคประกอบด้วยนักแสดง กริยา และเป้าหมายเสมอ ลำดับที่สิ่งเหล่านี้มากำหนดว่าประโยคนั้นเขียนด้วยเสียงที่ใช้งานหรือแบบพาสซีฟ

นักแสดงมาก่อนใน an เสียงที่ใช้งาน. ตัวอย่างเช่น: “CSS วาดพื้นหลัง”

ประโยคที่ใช้เสียงพูดตรงไปตรงมามากกว่าประโยค ชัดเจนขึ้น สั้นลง และเข้าใจได้มากขึ้น เหมาะอย่างยิ่งสำหรับเสียงที่เป็นมืออาชีพและตรงประเด็นมากขึ้น

กับ กรรมวาจก, นักแสดงมาทีหลัง (ดูสิ่งที่ฉันทำที่นั่น) นั่นหมายความว่านักแสดงของเรา - CSS ในกรณีนี้ - มาที่ส่วนท้ายดังนี้: "พื้นหลังถูกวาดโดย CSS"

ผู้อ่านมักจะแปลง passive voice เป็น active voice ในหัว ส่งผลให้ใช้เวลาในการประมวลผลมากขึ้น หากคุณเคยได้ยินว่าการเขียนด้วยเสียงที่กระฉับกระเฉงดีกว่า นี่ก็เป็นเหตุผลว่าทำไม นักเขียนด้านเทคนิคชอบใช้เสียงพูดเป็นส่วนใหญ่ โดยมีข้อยกเว้นเพียงเล็กน้อย เช่น การอ้างถึงงานวิจัย: “มีคนแนะนำว่า …”

แต่นั่นไม่ได้หมายความว่าคุณควรพยายามหาเสียงที่กระตือรือร้นอยู่เสมอ การเปลี่ยนจากประโยคหนึ่งไปยังอีกประโยคหนึ่ง แม้จะอยู่ในย่อหน้าเดียวกันก็ตาม สามารถทำให้เนื้อหาของคุณไหลลื่นจากประโยคหนึ่งไปอีกประโยคหนึ่งได้อย่างราบรื่นยิ่งขึ้นหากใช้อย่างมีประสิทธิภาพ

หลีกเลี่ยงความผิดพลาด

ไวยากรณ์เป็นเรื่องเกี่ยวกับโครงสร้างและความถูกต้องของภาษา และไม่มีอะไรดีไปกว่าการตรวจสอบเอกสารของคุณอย่างรวดเร็ว เป็นสิ่งสำคัญมากที่จะกำจัดงานเขียนที่สะกดผิด ปัญหาด้านไวยากรณ์ และความไม่สมบูรณ์ของความหมาย

ในตอนท้ายของบทความนี้ ฉันจะแสดงให้คุณเห็นถึงเครื่องมืออันล้ำค่าที่มืออาชีพใช้เพื่อหลีกเลี่ยงการเขียนผิดพลาด เห็นได้ชัดว่ามีเครื่องตรวจการสะกดในตัวในแทบทุกอย่างในทุกวันนี้ โปรแกรมแก้ไขโค้ดของเรามีปลั๊กอินตรวจสอบตัวสะกดและช่วยป้องกันไม่ให้เกิดข้อผิดพลาด 

แต่ถ้าคุณกำลังมองหาเครื่องมือแบบครบวงจรสำหรับไวยากรณ์ทุกอย่าง Grammarly เป็นหนึ่งในเครื่องมือที่ใช้กันอย่างแพร่หลายมากที่สุด ฉันไม่ได้รับเงินคืนสำหรับสิ่งนั้นหรืออะไรก็ตาม เป็นเครื่องมือที่ยอดเยี่ยมมากที่บรรณาธิการและนักเขียนจำนวนมากใช้เพื่อเขียนเนื้อหาที่ชัดเจนและชัดเจน คล้ายกับวิธีที่คุณอาจใช้ Emmet, eslint หรือ linter อื่นๆ ในการเขียนโค้ดที่ชัดเจนและชัดเจน

การเขียนโค้ดคอมเมนต์

สิ่งที่เราเขียนสำหรับนักพัฒนาคนอื่นๆ อาจส่งผลกระทบอย่างมากต่อคุณภาพโดยรวมของงาน ไม่ว่าจะเป็นสิ่งที่เราเขียนในโค้ด วิธีที่เราอธิบายโค้ด หรือวิธีที่เราให้คำติชมเกี่ยวกับโค้ด

เป็นเรื่องที่น่าสนใจที่ทุกภาษาการเขียนโปรแกรมมาพร้อมกับชุดคุณสมบัติมาตรฐานในการเขียนความคิดเห็น พวกเขาควรอธิบายว่าโค้ดกำลังทำอะไรอยู่ ฉันไม่ได้หมายถึงความคิดเห็นที่คลุมเครือเช่นนี้

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

ให้ใช้ความคิดเห็นที่ให้ข้อมูลเพิ่มเติมแทน:

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

มันคือทั้งหมดที่เกี่ยวกับบริบท “ฉันกำลังสร้างโปรแกรมประเภทใด” เป็นคำถามที่คุณควรถามตัวเอง

ความคิดเห็นควรเพิ่มมูลค่า

ก่อนที่เราจะดูว่าความคิดเห็นเกี่ยวกับโค้ด "ดี" คืออะไร ต่อไปนี้คือตัวอย่างความคิดเห็นขี้เกียจ XNUMX ตัวอย่าง:

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

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

จำไว้ว่าจุดประสงค์ของความคิดเห็นคือการเพิ่มมูลค่าให้กับโค้ด ไม่ใช่เพื่อทำซ้ำ หากคุณทำไม่ได้ คุณควรปล่อยให้รหัสเหมือนเดิมดีกว่า สิ่งที่ทำให้ตัวอย่างเหล่านี้ “เกียจคร้าน” คือพวกเขาเพียงแต่ย้ำสิ่งที่โค้ดกำลังทำอย่างเห็นได้ชัด ในกรณีนี้ ความคิดเห็นซ้ำซากเพราะพวกเขาบอกเราในสิ่งที่เรารู้อยู่แล้ว — ไม่ได้เพิ่มมูลค่า!

ความคิดเห็นควรสะท้อนถึงรหัสปัจจุบัน

ความคิดเห็นที่ล้าสมัยไม่ใช่เรื่องที่หาได้ยากในโครงการขนาดใหญ่ ฉันกล้าพูดใน มากที่สุด โครงการ

ลองนึกภาพว่า David เป็นโปรแกรมเมอร์และหนุ่มสุดเท่ที่จะออกไปเที่ยวด้วย David ต้องการจัดเรียงรายการสตริงตามตัวอักษรจาก A ถึง Z ดังนั้นเขาจึงทำอย่างชัดเจนใน JavaScript:

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

จากนั้น David ก็ตระหนักว่า sortWords() นั้นเรียงลำดับรายการจาก Z ถึง A จริง ๆ นั่นไม่ใช่ปัญหา เนื่องจากเขาสามารถย้อนกลับผลลัพธ์ได้:

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

น่าเสียดายที่ David ไม่ได้อัปเดตความคิดเห็นเกี่ยวกับโค้ดของเขา

ลองนึกภาพว่าฉันไม่ได้เล่าเรื่องนี้ให้คุณฟัง และสิ่งที่คุณเห็นคือโค้ดด้านบน คุณคงคิดว่าหลังจากรันโค้ดบรรทัดที่สองแล้ว `เมือง' จะถูกจัดเรียงจาก Z ถึง A! ความสับสนทั้งหมดนี้เกิดจากความคิดเห็นที่ล้าสมัย

แม้ว่านี่อาจเป็นตัวอย่างที่เกินจริง แต่สิ่งที่คล้ายกันสามารถเกิดขึ้นได้ (และมักจะเกิดขึ้น) หากคุณแข่งกับเส้นตายที่ใกล้จะถึง โชคดีที่สิ่งนี้สามารถป้องกันได้โดยทำตามกฎง่ายๆ... เปลี่ยนความคิดเห็นของคุณในเวลาเดียวกับที่คุณเปลี่ยนรหัส

นั่นเป็นกฎง่ายๆ ข้อหนึ่งที่จะช่วยคุณและทีมของคุณจากหลายๆ อย่าง หนี้ทางเทคนิค.

ตอนนี้เรารู้แล้วว่าความคิดเห็นที่เขียนไม่ดีเป็นอย่างไร มาดูตัวอย่างที่ดีกัน

ความคิดเห็นควรอธิบายรหัส Unidiomatic

บางครั้ง ธรรมชาติ วิธีการทำสิ่งต่าง ๆ ไม่ถูกต้อง โปรแกรมเมอร์อาจต้อง "ทำลาย" มาตรฐานเล็กน้อย แต่เมื่อพวกเขาทำ ขอแนะนำให้แสดงความคิดเห็นเล็กน้อยเพื่ออธิบายเหตุผลของพวกเขา:

 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 คำอธิบายสรุป อะไร มีการเปลี่ยนแปลงและ ทำไม มันถูกสร้างขึ้น โครงการขนาดใหญ่มีเทมเพลตคำขอดึง แบบนี้ดัดแปลงมาจาก a ตัวอย่างจริง:

## 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 ชื่อ

โปรดหลีกเลี่ยงชื่อที่มีลักษณะดังนี้:

• แก้ไขบิลด์
• แก้ไขข้อบกพร่อง
• เพิ่มแพตช์.

เหล่านี้ไม่ได้ ความพยายาม เพื่ออธิบายว่าเรากำลังจัดการกับบิลด์ บั๊ก หรือแพตช์ใด รายละเอียดเพิ่มเติมเล็กน้อยเกี่ยวกับส่วนใดของบิลด์ที่ได้รับการแก้ไข จุดบกพร่องใดที่ถูกบีบอัด หรือแพตช์ใดที่เพิ่มเข้าไปสามารถช่วยให้การสื่อสารและการทำงานร่วมกันกับเพื่อนร่วมงานของคุณดีขึ้น มันกำหนดระดับและทำให้ผู้คนอยู่ในหน้าเดียวกัน

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.

รวบรวมภาพหน้าจอ

บันทึกปัญหาโดยใช้ your ยูทิลิตี้ถ่ายภาพหน้าจอของระบบ.

หากเป็นภาพหน้าจอของ a 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.

แนะนำสาเหตุ

คุณเป็นคนเดียวที่ตรวจพบบั๊ก ดังนั้นคุณอาจแนะนำสาเหตุที่เป็นไปได้ว่าทำไมมันถึงอยู่ที่นั่น บางทีข้อผิดพลาดอาจเกิดขึ้นหลังจากที่คุณพบเหตุการณ์บางอย่างเท่านั้น หรืออาจเกิดขึ้นบนมือถือเท่านั้น

การสำรวจ codebase อาจไม่เสียหาย และอาจระบุสาเหตุของปัญหาได้ จากนั้น ปัญหาของคุณจะถูกปิดเร็วขึ้นมาก และคุณน่าจะได้รับมอบหมายให้ดูแลที่เกี่ยวข้อง PR.

สื่อสารกับลูกค้า

คุณอาจทำงานเป็นฟรีแลนซ์เดี่ยว หรือบางทีคุณอาจเป็นหัวหน้านักพัฒนาในทีมเล็กๆ ไม่ว่าในกรณีใด สมมติว่าคุณมีหน้าที่รับผิดชอบในการติดต่อกับลูกค้าในโครงการ 

ตอนนี้ ทัศนคติของโปรแกรมเมอร์คือเราเป็นนักสื่อสารที่แย่ เป็นที่ทราบกันดีว่าเราใช้ศัพท์เฉพาะทางเทคนิคที่มากเกินไป บอกผู้อื่นว่าอะไรเป็นไปได้และเป็นไปไม่ได้ และแม้กระทั่งรับการป้องกันเมื่อมีคนตั้งคำถามถึงแนวทางของเรา

แล้วเราจะลดความคิดเหมารวมนั้นได้อย่างไร? ถามลูกค้าว่าต้องการอะไร และรับฟังความคิดเห็นของลูกค้าเสมอ นี่คือวิธีการทำเช่นนั้น

ถามคำถามที่เหมาะสม

เริ่มต้นด้วยการตรวจสอบให้แน่ใจว่าคุณและลูกค้าอยู่ในหน้าเดียวกัน:

• ผู้ชมเป้าหมายของคุณคือใคร
• เป้าหมายของเว็บไซต์คืออะไร?
• ใครคือคู่แข่งที่ใกล้เคียงที่สุดของคุณและพวกเขากำลังทำอะไรอยู่?

การถามคำถามเป็นวิธีที่ดีในการเขียนในเชิงบวก โดยเฉพาะอย่างยิ่งในสถานการณ์ที่คุณไม่เห็นด้วยกับความคิดเห็นหรือการตัดสินใจของลูกค้า การถามคำถามบังคับให้บุคคลนั้นสนับสนุนการอ้างสิทธิ์ของตนเองแทนที่จะโจมตีพวกเขาโดยปกป้องตำแหน่งของคุณเอง:

• คุณตกลงกับสิ่งนั้นแม้ว่าจะมาพร้อมกับต้นทุนประสิทธิภาพเพิ่มเติมหรือไม่?
• การย้ายส่วนประกอบช่วยให้เราบรรลุวัตถุประสงค์ได้ดีขึ้นหรือไม่
• เยี่ยมมาก ใครมีหน้าที่รับผิดชอบดูแลมันหลังจากเปิดตัว? 
• คุณรู้หรือไม่ว่าความแตกต่างระหว่างสองสีนั้นผ่านมาตรฐาน WCAG AA หรือไม่?

คำถามนั้นไร้เดียงสาและส่งเสริมความอยากรู้อยากเห็นมากกว่าความเป็นปฏิปักษ์

ขายเอง

หากคุณกำลังเสนอขายต่อผู้มีโอกาสเป็นลูกค้า คุณจะต้องโน้มน้าวให้พวกเขาจ้างคุณ ทำไมลูกค้าควรเลือกคุณ? สิ่งสำคัญคือต้องระบุสิ่งต่อไปนี้:

• คุณเป็นใคร
• สิ่งที่คุณทำ
• ทำไมคุณถึงเหมาะสมกับงาน
• ลิงก์ไปยังงานที่เกี่ยวข้องที่คุณทำ

และเมื่อคุณได้งานและจำเป็นต้องเขียนสัญญา จำไว้ว่าไม่มีเนื้อหาใดที่น่ากลัวไปกว่ากลุ่มคนถูกกฎหมาย แม้ว่าจะเขียนขึ้นสำหรับโครงการออกแบบ นักฆ่าสัญญา อาจเป็นจุดเริ่มต้นที่ดีในการเขียนสิ่งที่เป็นมิตรมากขึ้น

ความใส่ใจในรายละเอียดของคุณอาจเป็นความแตกต่างระหว่างคุณและนักพัฒนารายอื่นที่พยายามจะชนะโครงการเดียวกัน จากประสบการณ์ของผม ลูกค้าจะจ้างนักพัฒนาที่คิดว่าจะสนุกกับการทำงานได้ง่ายดายพอๆ กับคนที่มีความสามารถทางเทคนิคหรือมีประสบการณ์มากที่สุดสำหรับงาน

การเขียนจุลภาค

ไมโครสำเนา เป็นศิลปะในการเขียนที่เป็นมิตรกับผู้ใช้ UI ข้อความต่างๆ เช่น ข้อผิดพลาด พนันได้เลยว่ามีหลายครั้งที่คุณในฐานะนักพัฒนาซอฟต์แวร์ต้องเขียนข้อความแสดงข้อผิดพลาดเนื่องจากข้อความเหล่านี้ถูกฝังไว้ที่แบ็คเบิร์นตลอดทางเพื่อเริ่มเวลา

นั่นอาจเป็นสาเหตุที่บางครั้งเราพบข้อผิดพลาดเช่นนี้:

Error: Unexpected input (Code 693)

ข้อผิดพลาดเป็นสิ่งสุดท้ายที่คุณต้องการให้ผู้ใช้จัดการ แต่มันเกิดขึ้น และเราไม่สามารถทำอะไรกับมันได้ ต่อไปนี้คือเคล็ดลับบางประการในการพัฒนาทักษะการใช้ไมโครสำเนาของคุณ

หลีกเลี่ยงศัพท์แสงทางเทคนิค

คนส่วนใหญ่ไม่รู้ว่าเซิร์ฟเวอร์คืออะไร ในขณะที่โปรแกรมเมอร์ 100% รู้จัก จึงไม่แปลกที่จะเห็นคำแปลก ๆ เขียนในข้อความแสดงข้อผิดพลาดเช่น API หรือ “การดำเนินการหมดเวลา”

เว้นแต่ว่าคุณกำลังติดต่อกับลูกค้าด้านเทคนิคหรือฐานผู้ใช้ เป็นไปได้ว่าผู้ใช้ส่วนใหญ่ของคุณไม่ได้เรียนหลักสูตรวิทยาการคอมพิวเตอร์ และไม่รู้ว่าอินเทอร์เน็ตทำงานอย่างไร และเหตุใดบางสิ่งจึงไม่ทำงาน จึงเกิดข้อผิดพลาด

ดังนั้นข้อความแสดงข้อผิดพลาดที่ดีจึงไม่ควรอธิบาย ทำไม มีบางอย่างผิดพลาด เนื่องจากคำอธิบายดังกล่าวอาจต้องใช้คำศัพท์ทางเทคนิคที่น่ากลัว จึงเป็นสิ่งสำคัญมากที่จะหลีกเลี่ยงการใช้ศัพท์แสงทางเทคนิค

ไม่เคยโทษผู้ใช้

ลองนึกภาพสิ่งนี้: ฉันกำลังพยายามเข้าสู่ระบบแพลตฟอร์มของคุณ ดังนั้นฉันจึงเปิดเบราว์เซอร์ เยี่ยมชมเว็บไซต์ของคุณ และป้อนรายละเอียดของฉัน จากนั้นฉันก็บอกว่า: “อีเมล/รหัสผ่านของคุณไม่ถูกต้อง”

แม้ว่าจะดูเหมือนเป็นเรื่องน่าทึ่งที่จะคิดว่าข้อความนี้เป็นศัตรู แต่ก็ทำให้ฉันรู้สึกโง่โดยไม่รู้ตัว Microcopy บอกว่าไม่ควรตำหนิผู้ใช้ ลองเปลี่ยนข้อความของคุณให้ไม่ค่อยคมนัก เช่น ตัวอย่างนี้ดัดแปลงมาจากการเข้าสู่ระบบของ Mailchimp: “ขออภัย ชุดรหัสผ่านอีเมลและรหัสผ่านไม่ถูกต้อง เราสามารถช่วยคุณกู้คืนบัญชีของคุณได้”

ฉันยังต้องการเพิ่มความสำคัญของการหลีกเลี่ยงตัวพิมพ์ใหญ่และเครื่องหมายอัศเจรีย์ทั้งหมดด้วย! แน่นอนว่าสามารถใช้เพื่อถ่ายทอดความตื่นเต้นได้ แต่ใน microcopy พวกเขาสร้างความรู้สึกเป็นปรปักษ์ต่อผู้ใช้

อย่าครอบงำผู้ใช้

การใช้อารมณ์ขันในไมโครสำเนาของคุณเป็นความคิดที่ดี! มันสามารถทำให้อารมณ์สว่างขึ้น และเป็นวิธีที่ง่ายในการควบคุมการปฏิเสธที่เกิดจากข้อผิดพลาดที่เลวร้ายที่สุด

แต่ถ้าใช้ไม่เป็น อย่างสมบูรณ์อาจมองว่าเป็นการดูถูกเหยียดหยามผู้ใช้ นั่นเป็นเพียง ใหญ่ เสี่ยงที่จะรับ

Mailchimp พูดได้ดี:

[ด] อย่าพยายามทำเรื่องตลก — อารมณ์ขันที่บังคับอาจเลวร้ายยิ่งกว่าไม่มีเลย ถ้าไม่แน่ใจให้ทำหน้าตรงๆ.

(เน้นของฉัน)

การเขียนมาร์กอัปที่เข้าถึงได้

เราสามารถใช้บทความทั้งบทความเกี่ยวกับการช่วยสำหรับการเข้าถึงและความเกี่ยวข้องกับการเขียนทางเทคนิคได้อย่างง่ายดาย แย่จัง การช่วยสำหรับการเข้าถึงมักจะรวมอยู่ในคู่มือสไตล์เนื้อหา ไมโครซอฟท์ และ MailChimp.

คุณเป็นนักพัฒนาและอาจรู้เรื่องการเข้าถึงได้ง่ายอยู่แล้ว คุณอาจเป็นหนึ่งในนักพัฒนาที่ขยันขันแข็งที่ทำให้การช่วยสำหรับการเข้าถึงเป็นส่วนสำคัญของเวิร์กโฟลว์ของคุณ ถึงกระนั้น ก็ยังเป็นเรื่องที่น่าเหลือเชื่อที่บ่อยครั้งที่การพิจารณาความสามารถเข้าถึงได้ง่ายถูกใส่ไว้ในแบ็คเบิร์น ไม่ว่าเราทุกคนจะรู้ว่าการสร้างประสบการณ์ออนไลน์ที่เข้าถึงได้ซึ่งรวมถึงความสามารถทั้งหมดนั้นสำคัญเพียงใด

ดังนั้น หากคุณพบว่าตัวเองใช้การเขียนคำโฆษณาของคนอื่นในโค้ดของคุณ การเขียนเอกสารสำหรับนักพัฒนาคนอื่นๆ หรือแม้แต่การเขียน UI ลอกเลียนตัวคุณเอง คำนึงถึงแนวทางปฏิบัติที่ดีที่สุดเกี่ยวกับการช่วยสำหรับการเข้าถึงขั้นพื้นฐาน เนื่องจากมีคำแนะนำอื่นๆ ทั้งหมดสำหรับการเขียนทางเทคนิค

สิ่งที่ชอบ:

Andy Bell เสนอค่อนข้างค่อนข้าง สิ่งเล็กๆ ที่คุณสามารถทำได้เพื่อทำให้เนื้อหาเข้าถึงได้ง่ายขึ้นและคุ้มค่ากับเวลาของคุณที่จะลองดู และสำหรับการเตะ John Rhea อวดเทคนิคการตัดต่อสุดเก๋ ที่เป็นไปได้เมื่อเราทำงานกับองค์ประกอบ HTML เชิงความหมาย

สรุป

นี่คือหกวิธีที่แสดงให้เห็นว่าการเขียนเชิงเทคนิคและการพัฒนาเกิดขึ้นพร้อมกันได้อย่างไร แม้ว่าตัวอย่างและคำแนะนำอาจไม่ใช่วิทยาศาสตร์จรวด ฉันหวังว่าคุณจะพบว่ามีประโยชน์ ไม่ว่าจะเป็นการทำงานร่วมกับนักพัฒนาคนอื่น ดูแลงานของคุณเอง ต้องเขียนสำเนาของคุณเองอย่างรวดเร็ว หรือแม้แต่ร่างข้อเสนอโครงการ และอื่นๆ สิ่งของ.

สิ่งสำคัญที่สุด: การฝึกฝนทักษะการเขียนของคุณให้เฉียบแหลมและพยายามมากขึ้นในการเขียนของคุณ จริงๆ แล้วจะทำให้คุณเป็นนักพัฒนาที่ดีขึ้นได้

แหล่งข้อมูลการเขียนทางเทคนิค

หากคุณสนใจในการเขียนเชิงเทคนิค:

หากคุณสนใจในการเขียนคำโฆษณา:

หากคุณสนใจในไมโครสำเนา:

หากคุณสนใจที่จะใช้คู่มือสไตล์มืออาชีพเพื่อปรับปรุงงานเขียนของคุณ:

หากคุณสนใจที่จะเขียนเพื่อการช่วยสำหรับการเข้าถึง: