คำถามติดแท็ก documentation

ผมเป็น (อย่างไม่เป็นทางการ) การค้นคว้าความหมาย / อภิปรัชญาวิธีการที่ใช้ในการเอกสารทางเทคนิคเมื่อฉัน stumbled เมื่อนี้อัญมณี : การเขียนโปรแกรมความรู้และเว็บแบบ Semantic เป็นแนวคิดจากเวลาที่ต่างกันซึ่งมีการเชื่อมต่อ กระดาษที่เชื่อมโยง, Literate Programming ใน XMLโดย Norman Walsh, กล่าวถึงเทคโนโลยี XML ที่เป็นศูนย์กลางของ semantic web แต่ฉันล้มเหลวในการเห็นการเชื่อมต่อเชิงความคิดระหว่างการเขียนโปรแกรมเชิงความรู้กับเอกสารทางเว็บเกี่ยวกับความหมายหรือ ontology ช่วยด้วย?

9 documentation  semantic-web  literate-programming 

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

9 documentation 

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

9 documentation  design  modeling 

ปิด คำถามนี้จะต้องมีมากขึ้นมุ่งเน้น ไม่ยอมรับคำตอบในขณะนี้ ต้องการปรับปรุงคำถามนี้หรือไม่ อัปเดตคำถามเพื่อให้มุ่งเน้นที่ปัญหาเดียวโดยแก้ไขโพสต์นี้ ปิดให้บริการใน4 ปีที่แล้ว เราอยู่ในสถานการณ์ที่ไม่ดีที่มีเอกสารน้อยมากเกี่ยวกับการปรับแต่งคนงานที่ผ่านมาของเราทำกับระบบที่สำคัญทางธุรกิจ มีการเปลี่ยนแปลงมากมายใน Crystal Reports เอนทิตีฐานข้อมูลและไฟล์การตั้งค่า / การเขียนโปรแกรมกรรมสิทธิ์สำหรับซอฟต์แวร์ ERP ของเรา เอกสารปัจจุบันโดยทั่วไปจะอ่านบางสิ่งเช่นนี้ โปรแกรมนี้ทำงานก่อนออกใบแจ้งหนี้ ข้อบกพร่องที่รู้จัก: ไม่มี เรียกใช้โปรแกรมนี้หลังจากติดตั้งซอฟต์แวร์ X เปลี่ยนฟิลด์ต่อไปนี้ในรายงานนี้: (โดยไม่มีคำอธิบายว่าอย่างไรหรือทำไม) ร้านไอทีของเรามีขนาดเล็กและในกรณีของซอฟต์แวร์ ERP งานส่วนใหญ่ถูกทิ้งให้กับคนคนเดียว แผนกไอทีและการบัญชีรู้บิตและชิ้นส่วน (บางครั้งก็ค่อนข้างมีประโยชน์) แต่ก็ยังไม่เพียงพอ ปัญหาอีกประการคือแผนกบัญชีของเราคิดว่าเรามีเอกสารที่ดี เป็นความจริงที่เราเก็บบันทึกจำนวนมากเกี่ยวกับสิ่งที่ผิดพลาดแต่มีคำอธิบายน้อยมากที่ทำ (ถ้ามี) เพื่อแก้ไขปัญหาเหล่านี้ เรามีเอกสารหลายร้อยข้อที่อธิบายข้อบกพร่อง แต่เอกสารที่อธิบายการเปลี่ยนแปลง (ดังที่แสดงด้านบน) เกือบไร้ประโยชน์ ฉันจะบันทึกเกี่ยวกับการเปลี่ยนแปลงในอดีตได้อย่างไรเมื่อฉันไม่รู้ว่าทำอะไรทั้งหมด ฉันสามารถเริ่มต้นด้วยการบันทึกสิ่งที่เราเปลี่ยนแปลง: ไฟล์, ตารางฐานข้อมูลและสิ่งที่เราต้องมีเพื่อให้ระบบทำงานได้ ฉันยังสามารถเอกสารสิ่งที่เราทำ ; เมื่อมีการเรียกใช้รายงานเหตุใดจึงมีคนบอกให้ใช้รายงาน / โปรแกรม X แต่เมื่อหนึ่งในสิ่งที่กำหนดเองเหล่านี้มีปัญหาฉันมักจะกลับไปที่จตุรัสหนึ่ง ฉันจะบันทึกสิ่งนี้ให้ฉันและคนอื่นได้อย่างไร

9 documentation 

ฉันต้องการเขียน Javadoc ด้วยวิธี DRY แต่เอกสาร oracle เกี่ยวกับJavadocกล่าวว่าเขียนสิ่งเดียวกันอีกครั้งในความคิดเห็นของเมธอด overload ฉันไม่สามารถหลีกเลี่ยงการทำซ้ำได้หรือไม่

9 documentation  comments  dry  javadocs 

ฉันกำลังใช้งานแอปพลิเคชันระดับองค์กรครั้งแรกของฉันและฉันต้องการให้ทีมของฉันสร้างแบบจำลองแอปพลิเคชัน ASP.NET MVC C # ทั้งหมดก่อนที่เราจะแตะโค้ดหนึ่งบรรทัด UPDATE: สิ่งนี้ไม่ได้มีวัตถุประสงค์เพื่อการอภิปรายเชิงปรัชญาเกี่ยวกับเวลาที่จะจัดทำเอกสาร / แบบจำลองแอปพลิเคชัน โปรดให้คำตอบสำหรับ "วิธี" กับเอกสาร / รุ่นเท่านั้น ความจริงก็คือฉันเคยอ่านในแผนกนี้มาตลอดและฉันไม่เคยทำแบบจำลองแอปพลิเคชันมาก่อน วิธีมาตรฐานในการทำเช่นนี้คืออะไร? ควรใช้ไดอะแกรมชนิดใดและเอกสารประกอบจะเป็นอย่างไร ลิงก์ไปยังไดอะแกรมตัวอย่างและเอกสารประกอบได้รับการชื่นชม เมื่อค้นหาฉันสามารถค้นหาสิ่งต่าง ๆ มากมายในเน็ต แต่ฉันต้องการดูว่ามีฉันทามติสมัยใหม่ในปัจจุบันเกี่ยวกับวิธีการทำสิ่งนี้หรือไม่ ขอบคุณล่วงหน้า! คำชี้แจงการปิด ฉันไม่รู้ว่านี่เป็นเรื่องที่เหนียวมาก ขอขอบคุณทุกท่านที่สามารถแยกความขัดแย้งที่เห็นได้ชัดและให้คำตอบที่เป็นประโยชน์ มันเป็นการสนทนาที่น่าสนใจที่จะพูดน้อยที่สุด :) ลิงค์ที่มีประโยชน์อื่นที่ฉันค้นพบคือ: /programming/61487/do-you-use-uml-in-agile-development-practices/61519#61519

9 c#  asp.net-mvc  documentation  uml 

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

9 project-management  documentation 

ฉันกำลังมองหาวิธีในการปรับปรุงการจัดการความต้องการ ขณะนี้เรามีเอกสาร Word ที่เผยแพร่บนเว็บไซต์ น่าเสียดายที่เราไม่สามารถดูการเปลี่ยนแปลงจากการแก้ไขครั้งต่อไปได้ ฉันชอบที่จะทำเช่นนั้นเหมือนกับ wiki หรือ VCS (หรือทั้งสองอย่างเช่น wiki บน bitbucket!) นอกจากนี้แต่ละเอกสารอธิบายการเปลี่ยนแปลง devs ที่คาดว่าจะพบตามกำหนดเวลาที่กำหนด ไม่มีการรวบรวมฟีเจอร์แอพสะสมที่มีการบันทึกไว้ที่ใด ๆ ดังนั้นบางครั้งก็ยากที่จะแยกแยะความแตกต่างระหว่างข้อบกพร่องและคุณสมบัติ (ออกแบบไม่ดี) เมื่อพยายามแก้ไขอย่างรวดเร็วไปยังแอปรุ่นเก่า ดังนั้นฉันจึงมีความคิดว่าฉันต้องการรับคำติชม เกี่ยวกับ: ใช้ wiki เพื่อให้เราสามารถติดตามได้ว่าใครเปลี่ยนอะไรบ้างเมื่อไหร่ (ส่วนใหญ่เพื่อดูว่ามีการแก้ไขใด ๆ นับตั้งแต่ครั้งล่าสุดที่มีคนดู) มีหนึ่งพูดหน้า wiki ต่อผลิตภัณฑ์มากกว่าหนึ่งต่อกำหนดให้ทันกับคุณลักษณะทั้งหมดของผลิตภัณฑ์มากกว่าการเปลี่ยนแปลงที่ควรดำเนินการ ด้วยวิธีนี้ฉันสามารถดูการแก้ไขหน้าเฉพาะเพื่อดูว่าแอปควรทำอะไรในเวลาที่กำหนดและฉันสามารถดู การเปลี่ยนแปลงของหน้าได้ตั้งแต่การวางจำหน่ายครั้งล่าสุดสำหรับข้อกำหนดที่จะดำเนินการภายในวันถัดไป . Waddayathink?

9 documentation  project-management  wiki  requirements 

นี่อาจเป็นคำถามที่โง่ แต่ก็อยู่ข้างหลังศีรษะของฉันซักพักแล้วและฉันไม่สามารถหาคำตอบที่เหมาะสมได้จากที่อื่น ฉันมีครูผู้หนึ่งที่บอกว่าเราควรระบุพารามิเตอร์แต่ละรายการด้วยคำอธิบายอย่างชัดเจนแม้ว่าจะมีเพียงพารามิเตอร์เดียวเท่านั้น สิ่งนี้นำไปสู่การซ้ำซ้อนมากมาย: double MyFunction(const int MyParam); // Function: MyFunction // Summary: Does stuff with MyParam. // Input: int MyParam - The number to do stuff with. // Output: MyParam with stuff done to it. เมื่อเขียนเอกสารในโค้ดคุณมีรายละเอียดมากน้อยเพียงใด?

9 documentation  comments  coding-style