แนวทางปฏิบัติที่ดีในการพัฒนาซอฟต์แวร์ที่เสรีและเปิดกว้าง: เอกสารประกอบ

La เอกสาร เป็นและควรเป็นส่วนพื้นฐานของไฟล์ กระบวนการสร้างสรรค์และการวางแผน ของกิจกรรมทั้งหมดของมนุษย์และอื่น ๆ ในสาขาเทคโนโลยีโดยเฉพาะอย่างยิ่งในด้าน การพัฒนาซอฟต์แวร์.

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

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

• 0: อิสระในการรันโปรแกรมตามที่คุณต้องการไม่ว่าด้วยวัตถุประสงค์ใด ๆ
• 1: อิสระในการเข้าถึงและศึกษาโปรแกรมและเปลี่ยนแปลงหรือดัดแปลงเพื่อประโยชน์ของคุณเอง
• 2: เสรีภาพในการแบ่งปันหรือแจกจ่ายสำเนาเพื่อเผยแพร่สิ่งเดียวกันและ / หรือช่วยเหลือผู้อื่น
• 3: อิสระในการแจกจ่ายสำเนาของเวอร์ชันที่แก้ไขของคุณไปยังบุคคลที่สาม

เอกสารที่ดีทำให้ผลิตภัณฑ์ที่สร้างขึ้น:

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

แนวปฏิบัติที่ดี: เอกสารประกอบ

พื้นฐาน

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

ไม่ได้สร้างเอกสารที่ดีเมื่อมันมาถึง พัฒนาซอฟต์แวร์ฟรีโอเพ่นซอร์ส หรือซอฟต์แวร์ประเภทอื่น ๆ คือการส่งไปยังผู้รับที่เป็นไปได้ (ผู้ใช้ผู้ดูแลระบบผู้ดูแลหรือนักพัฒนาอื่น ๆ ) เพื่อหาทางผ่านป่าโดยไม่มีแผนที่หรือเข็มทิศ

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

แนวปฏิบัติที่ดีเกี่ยวกับเอกสารในไฟล์ข้อความ README

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

สำหรับบทความของเราเราได้นำไฟล์ แนวปฏิบัติที่ดี คิดและเปิดเผยโดย "รหัสสำหรับการริเริ่มการพัฒนา" เดล ธนาคารเพื่อการฟื้นฟูระหว่างประเทศอเมริกันซึ่งโดยสรุปจะบอกเราว่าเอกสารที่ดีตามไฟล์ ไฟล์ข้อความ README.md (หรือ. txt) จะต้องมีโครงสร้างดังนี้:

โครงสร้างไฟล์ README ที่แนะนำ

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

ในสิ่งเหล่านี้ แนวปฏิบัติที่ดีนอกจากนี้ยังแนะนำให้เพิ่มไฟล์ เอกสารไฟล์ README เพื่อให้สมบูรณ์ยิ่งขึ้นส่วนต่อไปนี้:

• วิธีการมีส่วนร่วม: ส่วนที่อธิบายถึงขั้นตอนการมีส่วนร่วมในโครงการสำหรับนักพัฒนาซอฟต์แวร์รายใหม่
• จรรยาบรรณ: ส่วนที่อธิบายจรรยาบรรณกำหนดบรรทัดฐานทางสังคมกฎและความรับผิดชอบที่บุคคลและองค์กรต้องปฏิบัติตามเมื่อมีปฏิสัมพันธ์กับเครื่องมือดิจิทัลหรือชุมชนของตนในทางใดทางหนึ่ง
• ป้าย: ส่วนที่แสดงป้าย (ภาพขนาดเล็กที่ฝังอยู่ใน README.md) ที่ระบุสถานะของเครื่องมือที่อ่านได้และกระชับ
• เวอร์ชัน: ส่วนที่ระบุรายการเวอร์ชันของเครื่องมือดิจิทัลและฟังก์ชันที่เพิ่มเข้ามาในแต่ละเวอร์ชัน
• กิตติกรรมประกาศ: ส่วนที่มีการรับทราบถึงบุคคลหรือองค์กรอื่น ๆ ที่มีส่วนร่วมในโครงการบางอย่าง

หากต้องการขยายข้อมูลนี้ในไฟล์ แนวปฏิบัติที่ดี ในเรื่องของ เอกสาร สำหรับการพัฒนา ซอฟแวร์ฟรี, โดย "รหัสสำหรับการริเริ่มการพัฒนา" เดล ธนาคารเพื่อการฟื้นฟูระหว่างประเทศอเมริกัน คุณสามารถคลิกที่ลิงค์ต่อไปนี้: เอกสารประกอบ - คำแนะนำสำหรับการเผยแพร่เครื่องมือดิจิทัล. และในสิ่งพิมพ์อื่น ๆ เราจะสำรวจส่วนที่อ้างถึง แนวปฏิบัติที่ดี บน การประเมินและการออกใบอนุญาต เดล ซอฟต์แวร์ฟรีและเปิด ตัวเอง

ข้อสรุป

เราหวังว่า Esta "โพสต์เล็ก ๆ น้อย ๆ ที่มีประโยชน์" บน «Buenas prácticas» ในสาขา «documentación» เพื่อสร้างเมื่อพัฒนา «Software libre y abierto»เป็นสิ่งที่น่าสนใจและเป็นประโยชน์สำหรับส่วนรวม «Comunidad de Software Libre y Código Abierto» และมีส่วนช่วยอย่างมากต่อการแพร่กระจายของระบบนิเวศที่ยอดเยี่ยมขนาดมหึมาและการเติบโตของการใช้งานและสำหรับ «GNU/Linux».

และสำหรับข้อมูลเพิ่มเติมอย่าลังเลที่จะเยี่ยมชมใด ๆ ห้องสมุดออนไลน์ ในขณะที่ OpenLibra y เจดไอที เพื่ออ่าน หนังสือ (PDF) ในหัวข้อนี้หรืออื่น ๆ พื้นที่ความรู้. สำหรับตอนนี้ถ้าคุณชอบสิ่งนี้ «publicación», อย่าหยุดแบ่งปัน กับคนอื่น ๆ ในไฟล์ เว็บไซต์ช่องกลุ่มหรือชุมชนที่ชื่นชอบ ของเครือข่ายสังคมโดยเฉพาะอย่างยิ่งฟรีและเปิดเป็น สัตว์แมสทอดอนหรือปลอดภัยและเป็นส่วนตัว Telegram.

หรือเยี่ยมชมหน้าแรกของเราที่ DesdeLinux หรือเข้าร่วมช่องทางการ โทรเลขของ DesdeLinux เพื่ออ่านและโหวตสิ่งพิมพ์ที่น่าสนใจนี้หรืออื่น ๆ «Software Libre», «Código Abierto», «GNU/Linux» และหัวข้ออื่น ๆ ที่เกี่ยวข้องกับ «Informática y la Computación»และ «Actualidad tecnológica».