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

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

10 documentation  domain-specific-languages 

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

10 documentation  specifications 

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

10 c++  documentation 

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

10 agile  documentation  methodology 

ปิด. คำถามนี้เป็นคำถามปิดหัวข้อ ไม่ยอมรับคำตอบในขณะนี้ ต้องการปรับปรุงคำถามนี้หรือไม่ อัปเดตคำถามเพื่อให้เป็นหัวข้อสำหรับ Software Engineering Stack Exchange ปิดให้บริการใน6 ปีที่ผ่านมา ซอฟต์แวร์ภายใน บริษัท ของเราถูกใช้สำหรับผู้ใช้จำนวนมากและฝ่ายฝึกอบรมขอให้เราทราบเคล็ดลับเกี่ยวกับรูปแบบเอกสารผู้ใช้ปลายทาง มีใครรู้บ้างว่าฉันสามารถหาตัวอย่างที่ดีของเอกสารคู่มือผู้ใช้ซอฟต์แวร์ที่แผนกฝึกอบรมใช้เป็นแรงบันดาลใจหรือเว็บไซต์ใด ๆ ที่มีคำแนะนำที่ดี นี่คล้ายกับคำถามนี้แต่ฉันกำลังมองหาเอกสารสำหรับผู้ใช้เพื่อใช้งานโดยผู้ใช้ที่ไม่ใช่ด้านเทคนิค

10 design  documentation  users 

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

10 development-process  documentation  source-code 

ฉันได้บันทึกรหัสไว้doxygenแล้ว แต่ฉันไม่ต้องการ HTML ที่เป็นค่าเริ่มต้น ฉันรู้ว่าฉันสามารถปรับแต่งได้ด้วยการให้ CSS หัวกระดาษท้ายกระดาษ ฯลฯ (เช่น GNOME) และฉันจะเพิ่มรหัส PHP ทั่วไปลงในไฟล์และบอกให้บันทึกได้.phpแต่นั่นไม่ใช่สิ่งที่ฉันต้องการจริงๆ . สิ่งที่ฉันต้องการคือผลลัพธ์เช่น MSDN ฉันไม่สามารถอธิบายได้จริงๆ คำถามของฉันคือมีความเป็นไปได้ในการใช้ doxygen กับบางสิ่งบางอย่างเช่นเทมเพลตหรือฉันต้องแสดงผล XML และแยกมันด้วยโปรแกรมอื่น

10 documentation  templates  documentation-generation 

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

10 java  php  algorithms  documentation  sql 

เรามีเอกสารจำนวนมากที่เกี่ยวข้องกับการพัฒนาซอฟต์แวร์ของเรา สิ่งเหล่านี้รวมถึงสิ่งต่าง ๆ เช่นความต้องการเอกสารการออกแบบ PDF ภายนอกไฟล์ลูกค้าคำแนะนำการทดสอบ ฯลฯ ปัจจุบันเอกสารเหล่านี้กระจัดกระจายไปทั่วสถานที่ (วิกิ "สถานที่บางแห่งในเครือข่าย" ฮาร์ดไดรฟ์สำหรับนักพัฒนาท้องถิ่น (!) และสถานที่เลวร้ายยิ่ง) วิธีที่ดีที่สุดในการติดตามพวกเขาคืออะไร? เนื่องจากเราใช้ visual studio (2010) เพื่อการพัฒนาของเราและเราไม่มีผู้พัฒนาที่ไม่ใช่นักพัฒนาในโครงการฉันคิดว่ามันเป็นความคิดที่ดีที่จะเก็บไว้ใน VS "ทางออก" ซึ่งจะช่วยให้พวกเขา ที่จะควบคุมแหล่งที่มาและเข้าถึงได้ในระดับสากลโดยนักพัฒนาทั้งหมด อย่างไรก็ตาม VS ดูเหมือนจะไม่ถูกสร้างขึ้นเพื่อทำสิ่งนี้ หากคุณแก้ไขไฟล์เอกสารใด ๆ แม้แต่ไฟล์ที่ตั้งค่าด้วยคุณสมบัติบิลด์ "ไม่มี", "ห้ามคัดลอก" VS จะต้องสร้างซอฟต์แวร์ใหม่ก่อนที่จะรันอีกครั้ง ไม่มีวิธีในการสร้าง "โครงการเอกสาร" ภายในโซลูชัน (เราใช้โครงการ C # ที่ว่างเปล่าสำหรับสิ่งนี้) Visual Studio และ Word / Excel ไม่สามารถควบคุมแหล่งสัญญาณได้ดี คุณไม่สามารถดูไฟล์ที่เช็คอินแล้วตัดสินใจที่จะทำการเปลี่ยนแปลงโดยไม่ต้องปิดไฟล์ก่อนไปที่โครงการและตรวจสอบด้วยตนเองก่อนที่จะทำการเปลี่ยนแปลง มันช้าและน่าเบื่อที่สุดเท่าที่จะทำได้ อย่างไรก็ตามนี่เป็นสิ่งที่ดีที่สุดสำหรับทีมของเรา …

10 version-control  documentation 

ในขณะที่ตรวจสอบการใช้งานฟังก์ชั่นของโปรแกรมเมอร์อื่นเพื่อคำนวณ CDF การแจกแจงแบบปกติฉันได้แนะนำให้แทนที่การใช้งานทั้งหมดด้วยฟังก์ชันในตัวของ Python หรือใช้ SciPy ซึ่งเป็นห้องสมุดวิทยาศาสตร์ทั่วไป โปรแกรมเมอร์อีกชี้ให้เห็นว่าค่าmath.erfc()มิได้scipy.stats.norm.cdf()ให้การค้ำประกันความแม่นยำใด ๆ ในเอกสารของพวกเขา ดังนั้นฉันจึงควรระมัดระวังเกี่ยวกับการเปลี่ยนอัลกอริทึมการประมาณ (ซึ่งนำมาจากแหล่งที่ได้รับการเคารพและมีขอบเขตข้อผิดพลาดที่เป็นเอกสาร ) ความจริงแล้วความคิดที่จะสงสัยความถูกต้องและแม่นยำของฟังก์ชั่นในตัวหรือห้องสมุดไม่เคยข้ามความคิดของฉัน หลังจากที่ทุกคนฉันได้รับการเรียกฟังก์ชั่นเหมือนsin()และsqrt()สำหรับปีโดยไม่ต้องคิดมาก - เหตุผลที่ควรmath.erf()หรือscipy.stats.norm.cdf()จะแตกต่างกันหรือไม่? แต่ตอนนี้ฉันกังวล คำถามของฉันคือ: โดยทั่วไปหากเอกสารไม่มีการกล่าวถึงเป็นพิเศษแสดงว่าฟังก์ชั่นเหล่านี้มีความถูกต้องสมบูรณ์ในตำแหน่งทศนิยมสุดท้ายภายในความแม่นยำที่นำเสนอโดยทศนิยมความแม่นยำสองเท่าของ IEEE หรือไม่? นั่นเป็นเรื่องจริงสำหรับ Python math.erf()หรือ SciPy scipy.stats.norm.cdf()หรือไม่? คุณจะบอกได้อย่างไร นี้หน้าคนสำหรับsin()กล่าวว่า ... ฟังก์ชั่นเหล่านี้อาจสูญเสียความแม่นยำเมื่อข้อโต้แย้งของพวกเขาอยู่ใกล้กับหลาย pi หรืออยู่ห่างจาก 0.0 ทำไมคำเตือนควรมีอยู่เมื่อฟังก์ชันไซน์เป็นคาบและสมมาตร ดูเหมือนว่าจะมีภาระที่ผู้เรียกเข้ารับการป้อนข้อมูลเป็นมาตรฐานเพื่อให้ได้ความแม่นยำสูงสุด ในทางตรงกันข้ามเอกสารของ Mozilla สำหรับMath.sin()บอกว่าไม่มีอะไรเกี่ยวกับความถูกต้องหรือความแม่นยำ นั่นหมายความว่ามันถูกต้องสมบูรณ์หรือเป็น "ความรู้ทั่วไป" ที่Math.sin()จะแม่นยำในบางสถานการณ์ใน JavaScript เช่นที่อื่นหรือไม่

9 documentation  math  floating-point  numeric-precision 

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

9 documentation 

ฉันกำลังทำงานในห้องสมุดขนาดเล็กที่ให้การใช้งานของตัวชี้วัดสตริงพื้นฐานที่รู้จักกันดี ส่วนใหญ่เพื่อการศึกษาของฉันเอง ดังนั้นการพัฒนาจึงเกิดขึ้นทุกครั้งที่ฉันมีเวลาว่าง ด้วยเหตุนี้ฉันจึงเป็นกระบวนการอัตโนมัติโดยอัตโนมัติดังนั้นฉันจึงสามารถเผยแพร่เวอร์ชันได้บ่อยเท่าที่ฉันทำงานโดยไม่ต้องใช้ความพยายามมากเกินไป อย่างไรก็ตามการบำรุงรักษาเอกสาร Java ยังคงเป็นภาระเพราะมันมีตัวอย่าง เนื่องจาก API วิวัฒนาการขึ้นฉันต้องตรวจสอบตัวอย่างแต่ละครั้งซ้ำแล้วซ้ำอีก มีวิธีที่ดีกว่าในการทำเช่นนี้? ฉันได้พิจารณาการย้ายเอกสารและตัวอย่างไปเป็นโครงการแยกต่างหาก (เช่นCaliper Tutorial ) เพื่อให้สามารถนำแฟคตอริ่งและคอมไพล์ไปพร้อมกับรหัสปกติอีกครั้ง อย่างไรก็ตามมันจะย้ายเอกสารออกไปจากชั้นเรียนที่มันเป็นเรื่องเกี่ยวกับ ใช่แล้ว ฉันต้องการเค้กและกินด้วย : D * <h2>Tokenization</h2> * * Tokenization cuts up a string into tokens e.g. * <code>chilperic ii son of childeric ii</code> is tokenized into * <code>[chilperic, ii, son, of, * childeric, …

9 java  documentation  javadocs 

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

9 documentation 

ฉันกำลังจะออกจากโครงการและก่อนที่เจ้านายของฉันจะขอให้ฉันทำเอกสารรหัส (ฉันยังไม่ได้บันทึกไว้เป็นอย่างดี) มันไม่ใช่เรื่องใหญ่โครงการไม่ซับซ้อนอย่างมาก แต่ฉันกำลังค้นหาสถานที่ในเอกสารของฉันที่ฉันอยากจะพูดว่า "แจ้งให้ทราบทางสาย XYZ ที่สิ่งนั้นเกิดขึ้นเช่นนั้น" ในกรณีนี้มันไม่เหมาะสมที่จะอ้างถึงหมายเลขบรรทัดที่ระบุเนื่องจากการเพิ่มหรือลบรหัสบรรทัดเดียวจะทำให้เอกสารในเอกสารล้าสมัยทันที มีวิธีปฏิบัติที่ดีที่สุดในการอ้างอิงบรรทัดรหัสเฉพาะโดยไม่อ้างอิงหมายเลขบรรทัดหรือไม่? ฉันได้พิจารณาทิ้งรหัสด้วยความคิดเห็นที่ชอบ: /* linetag 38FECD4F */ โดยที่ "38FECD4F" เป็นแท็กที่ไม่ซ้ำกันสำหรับบรรทัดนั้น จากนั้นฉันสามารถใส่เอกสาร "ในบรรทัดที่ติดแท็ก '38FECD4F' โปรดสังเกตว่าเกิดขึ้นเช่นนั้น" ความคิดอื่น ๆ ? ฉันรู้สึกเหมือนเป็นการดีกว่าที่จะจัดทำเอกสารรหัสหน่วยโดยรวมมากกว่าเฉพาะบางส่วนของพวกเขา แต่ในกรณีของโครงการนี้โดยเฉพาะมีการใช้รหัสขั้นตอนยาวซึ่งไม่เคยได้รับการปรับสภาพเป็นหน่วยเล็ก ๆ

9 documentation  comments 

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

9 documentation  business-rules