การจัดทำเอกสารภาษาการเขียนโปรแกรม: คู่มืออ้างอิง

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

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

อะไรคือประเด็นสำคัญของคำหลักแต่ละคำที่บันทึกไว้?

• วากยสัมพันธ์
• ลักษณะ
• อาร์กิวเมนต์ - ถ้ามี
• ส่งคืนค่า - ถ้ามี
• ตัวอย่างการใช้งาน?
• อื่น ๆ ที่ฉันหายไป?

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

---

_{นี่คือการบริโภคภายนอก เรามีชุดเอกสารทั้งหมดแล้ว (ดู: http://www.rocketsoftware.com/u2/resources/technical-resources ) ทำงานในสิ่งที่เราควรทำแตกต่าง - ฉันมีความคิดอยู่แล้ว แต่เช่นเคยฉันพยายามไม่พึ่งพาความคิดเห็นของฉัน แต่เพียงผู้เดียว}

_{ผู้ชม: นักพัฒนาด้านเทคนิคใช้ฐานข้อมูลและเครื่องมือในการผลิตซอฟต์แวร์ในหลายอุตสาหกรรม}

จัดระเบียบเอกสารตามความต้องการของกลุ่มเป้าหมาย

ในกรณีของคุณผู้ชมหลักคือนักพัฒนาซอฟต์แวร์ ส่วนที่ควรพิจารณาในที่นี้คือเพื่อกล่าวถึง "กลุ่มเป้าหมายย่อย" ที่แตกต่างกันของส่วนนี้:

1. สวัสดีชาวโลก.
   ผู้ที่ต้องการรับรสชาติอย่างรวดเร็วเพียงสร้างและเรียกใช้แอปพลิเคชันตัวอย่างเพื่อดูว่ามีลักษณะอย่างไร
   นึกถึงผู้ชมอย่างหนึ่งที่ได้รับการจัดการโดย MySQL "กฎ 15 นาที" :
   

   _{... ผู้ใช้สามารถมี MySQL และทำงานได้ 15 นาทีหลังจากที่เขาดาวน์โหลดเสร็จ}

2. ความรู้พื้นฐาน
   สำหรับผู้ที่ต้องการเรียนรู้สิ่งที่จำเป็นในการเริ่มผลิตซอฟต์แวร์ที่ใช้งานได้อย่างรวดเร็ว
3. หัวข้อขั้นสูง
   สำหรับนักพัฒนาที่คุ้นเคยและมีพื้นฐานดีอยู่แล้วสนใจที่จะรู้ว่ามีอะไรมากกว่านั้น หัวข้อหลักที่ยังไม่ได้รับการคุ้มครองในความรู้พื้นฐาน
4. คู่มือสไตล์ / แนวทางปฏิบัติที่แนะนำ
   คำแนะนำส่วนตัวและคำแนะนำสำหรับผู้ที่สนใจในวิธีที่คุณแนะนำให้ทำสิ่งต่าง ๆ
   _{คำถามไม่ได้ระบุว่าสิ่งนี้อาจมีผู้ชมจำนวนมากในกรณีของคุณดังนั้นตัวเลือกในการพิจารณาคือการรวมไว้ในส่วน / ภาคผนวกของหัวข้อขั้นสูงหรือแม้กระทั่งลดลงอย่างสมบูรณ์}
5. นิสัยใจคอ
   ปิดบังหัวข้อนอกเหนือจากกระแสหลักที่อาจเป็นที่สนใจของผู้ชมของคุณในจำนวนที่ จำกัด ตัวอย่างเช่นหากคุณมีสายดั้งเดิมหรือสิ่งต่าง ๆ เช่นการอัพเกรด / การโยกย้าย / การทำงานร่วมกันกับมรดก - วางไว้ที่นี่ หากมีผลข้างเคียงบางอย่างสำหรับฟังก์ชั่นบางอย่างที่สภาพแวดล้อม "แปลกใหม่" มันจะไปในส่วนนี้

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

^{เกิดอะไรขึ้นถ้าสิ่งที่อยู่ในคู่มือสงสัย / ไม่ชัดเจน? ถ้าหากปรากฎว่าคำอธิบายอย่างละเอียดเกี่ยวกับแนวคิดบางอย่างจะทำให้คู่มือเล่มนั้นอ่านยากเกินไป? จะเกิดอะไรขึ้นหากคู่มือฉบับนั้นมีข้อผิดพลาด?}

สองสิ่งที่ควรพิจารณาสำหรับผู้ดูแลคือ:

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

   _{ข้อผิดพลาด> พื้นฐาน> Release 2.2> Typo ที่หน้า 28 ประโยคที่สองเริ่มต้นด้วยโชคอ่านล็อคแทน}

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

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

---

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

_{สุดท้าย แต่ไม่ใช่อย่างน้อยที่สุดให้พิจารณาตั้งค่าการพัฒนาเอกสารในลักษณะที่คล้ายคลึงกับการพัฒนาซอฟต์แวร์ ฉันหมายถึงสิ่งต่าง ๆ เช่นการควบคุมเวอร์ชันการวางจำหน่ายตามปกติการติดตามปัญหาการประกันคุณภาพเป็นต้นคุณอาจต้องการประนีประนอมบ้างแม้ว่ามันจะปรากฏว่านักเขียนด้านเทคนิคของคุณไม่พอใจกับสิ่งเหล่านี้ เราไม่ต้องการรับเนื้อหาที่“ เสแสร้ง” เพื่อกระบวนการพัฒนาที่สมบูรณ์แบบใช่ไหม?}

สิ่งแรกที่คุณต้องทำคือการประเมินผู้ชม ผู้ชมของคุณเป็นแฮกเกอร์เคอร์เนล Linux หรือเป็นนักออกแบบฮาร์ดแวร์ที่ใช้เครื่องมือซอฟต์แวร์เพื่อทำงาน แต่ไม่สนใจซอฟต์แวร์ต่อ se และไม่มีพื้นหลัง CS วิศวกรไฟฟ้ามีแนวโน้มที่จะไม่ชัดเจนเกี่ยวกับความแตกต่างระหว่างการโต้แย้งแบบ const และ non-const, ตัวชี้ไปยังวัตถุกับการอ้างอิงเป็นต้นหากแบบดั้งเดิมของคุณมีชื่อมากไปคุณควรอธิบายแนวคิดนั้นในระดับที่เหมาะสมสำหรับผู้ชมของคุณ ซึ่งอาจจะไม่มีอะไรถ้าพวกเขาเป็นโปรแกรมเมอร์ C ++

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

ต้องแน่ใจว่าได้รวมคำอธิบายของผลข้างเคียงใด ๆของฟังก์ชั่นของคุณ

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

ตามเนื้อผ้านักเขียนที่มีเทคโนโลยีมีความโดดเด่นระหว่างคู่มืออ้างอิงและคู่มือการใช้งาน คู่มืออ้างอิงมักจะมีข้อกำหนดทางไวยากรณ์คำจำกัดความที่เข้าใจได้ของฟังก์ชั่นหรือคำศัพท์พื้นฐานการอภิปรายของ gotcha ประสิทธิภาพและผลข้างเคียงและการใช้ตัวอย่างสั้น ๆ คู่มือผู้ใช้รวมถึงตัวอย่างการใช้งานเพิ่มเติมและการอภิปรายปัญหาทางวิศวกรรมที่กว้างขึ้น Kernigan และ Ritchie "ภาษาการเขียนโปรแกรม C" เป็นตัวอย่างที่ดีเยี่ยมในการประชุมนี้ แต่วิธีการนี้ใช้ได้เฉพาะเมื่อภาษาที่คุณใช้ทำเอกสารค่อนข้างง่าย

ผู้เขียนเป็นผู้จัดการฝ่ายวิศวกรรมบริการที่ศูนย์พัฒนาของ Ready Systems Inc ระหว่างปีพ. ศ. 2530 และ 2534 โดยรับผิดชอบในการจัดการทีมนักเขียนเทคโนโลยีห้าคน