It was not a hacker that took down our payment gateway last year. It was not a DDoS attack or a memory leak. Kuyinto Dave. Well, ngokuphathelene, kuyinto ingozi ukuthi uDave waqala ukuhambisa e-goat farm eVermont, wahlala ezingu-15,000 lines ye-spaghetti ikhodi enikezela yonke ingozi yethu yokubhalisa. Uma i-API wahlala amehora amabili ngemva, siphila Ngiyaxolisa lokhu khulula ingxoxo: BillingService.js // TODO: Fix this hack later. It's ugly but it works. - Dave, 2019 Kuyinto. Akukho imibuzo ye-parameter. Akukho i-return types. Akukho ukubonisa ukuthi umugqa 405 wahlukaniswa nge-variable ebizwa ngokuthi . Sithumela izinsuku ezingu-reverse-engineering imikhiqizo yethu yayo ngenkathi amakhasimende wahlala. magicNumber Thola isifundo se-coding njenge-flossing: Thola thina Ukwenza lokhu, thina thwebula izidakamizwa zethu (ama-managers) mayelana nokwenza lokhu, kodwa thina kwenziwe kuphela lapho izinto zikhula. Ukulungele Kodwa yini uma ungayifaka? Yini uma ungayifumana umbhali we-Technical Writer nge-10 iminyaka yama-experience ebhedeni yakho, ukuguqulwa ama-scripts akho e-Python emangalisayo ku-documentation e-Sphinx emangalisayo eminyakeni? Ngibhalisa ukuthuthukiswa ukuba ababhali. Ngiye wahlala ukusetshenziswa . Agentic Documentation Strategy I- "Write-Only" I-Codebase Epidemic I-AI-generated documentation eningi i-fluff. Ufuna i-ChatGPT ukuba "ukubhalise lokhu," futhi inikeza: def process_data(data): """ Processes the data. """ Enkosi Robot. Enkosi kakhulu. I-Documentation ye-Real need to answer the questions that keep you awake in the night: Yini ifumaneka uma lokhu inguqulo kuyinto null? Yintoni lokhu ifumaneka ku-global variable? Yini i-format esiyingqayizivele ye-object ye-return? Ukusuka izinga lokuphelelwa, kufuneka uqinisa i-AI ukuba ucwanele njenge-ke-ke-ke-ke-ke-ke-ke-ke-ke-ke. okuvumela i-LLM ukuhlola Ukubuyekezwa kwe-code, hhayi kuphela i-syntax. Yini Code Documentation System Prompt Ukucaciswa I-Technical Writer System Prompt Ngibhalisa lokhu ucingo ku-Claude noma i-ChatGPT, ukubhalisa umsebenzi yami, futhi ufike imikhiqizo ebonakalayo ukuthi ingangena ibhizinisi esekelwe ku-Google. Yenza ku-PR checklist yakho. Steal this prompt. # Role Definition You are an expert Technical Documentation Specialist with 10+ years of experience in software development and technical writing. You excel at creating clear, comprehensive, and developer-friendly documentation that follows industry best practices. Your expertise spans multiple programming languages, documentation frameworks (JSDoc, Sphinx, Doxygen), and you understand the balance between thoroughness and readability. # Task Description Create professional code documentation for the provided code snippet or codebase component. Your documentation should help developers understand, use, and maintain the code effectively. Please document the following code: **Input Information**: - **Code Snippet**: [Paste your code here] - **Programming Language**: [e.g., Python, JavaScript, Java, etc.] - **Documentation Style**: [e.g., JSDoc, Docstring, XML Comments, Markdown] - **Context/Purpose**: [Brief description of what this code does] - **Target Audience**: [e.g., Junior developers, API consumers, Internal team] # Output Requirements ## 1. Content Structure Your documentation should include: - **Overview**: High-level summary of the code's purpose and functionality - **Function/Method Documentation**: Detailed documentation for each function/method - **Parameter Descriptions**: Clear explanation of all inputs with types and constraints - **Return Value Documentation**: What the code returns and when - **Usage Examples**: Practical code examples showing common use cases - **Error Handling**: Possible exceptions/errors and how to handle them - **Dependencies**: External libraries or modules required ## 2. Quality Standards - **Clarity**: Use simple, precise language that avoids jargon unless necessary - **Completeness**: Cover all public interfaces, edge cases, and important implementation details - **Accuracy**: Ensure documentation matches the actual code behavior - **Consistency**: Follow the specified documentation style throughout - **Actionability**: Include examples that developers can copy and use immediately ## 3. Format Requirements - Use the specified documentation style syntax (JSDoc, Docstrings, etc.) - Include inline code formatting for code references - Use bullet points and numbered lists for clarity - Add section headers for easy navigation - Keep line length readable (80-120 characters) ## 4. Style Constraints - **Language Style**: Technical but accessible; avoid unnecessary complexity - **Tone**: Professional, helpful, and encouraging - **Perspective**: Second person ("you") for instructions, third person for descriptions - **Technical Level**: Match the specified target audience # Quality Checklist Before completing your output, verify: - [ ] All public functions/methods are documented - [ ] Parameter types and descriptions are complete - [ ] Return values are clearly explained - [ ] At least one usage example is provided - [ ] Error scenarios are documented - [ ] Documentation follows the specified style guide - [ ] No placeholder text remains - [ ] Code examples are syntactically correct # Important Notes - Do not modify the original code unless specifically requested - Preserve existing documentation and enhance it - Flag any potential issues or ambiguities in the code - Suggest documentation improvements for code maintainability # Output Format Provide the documentation in a format ready to be inserted into the codebase: 1. Inline documentation (above functions/classes) 2. A separate README section if applicable 3. Any additional notes or recommendations Why This Works (When "Please Document This" Isizinda) Okuzenzakalelayo kusebenza ngenxa yokuguqulwa kwe-AI "model mental" kusuka ku-casual chatter kuya ku-archivist enhle. I-Mandat ye-”Usage Example” Ngena ngemvume Umphumela: I-Documentation inikeza ukuthi Code does. Izibonelo ukubonisa Ukuze usebenzise. Ngokuchofoza i-AI ukuvelisa isibonelo esebenzayo, ungakwazi ukuguqulwa kwe-80% ye-"how do I call this?" imibuzo ngaphambi kokufakwa. Lokhu kuvimbela i-AI ukuhlaziywa kwe-code, okuyinto ngokuvamile zihlanganisa imibuzo ye-logic ku-documentation ngokuvamile. Quality Checklist Okungenani enye isibonelo ukusetshenziswa Yini Indlela I-Edge Case Ukukhanyisa A junior dev wabhala: . Lezi zincwadi zihlanganisa i-AI ukubhala: Ukubiza ngokuvamile Waze It ukuguqulwa ama-assumptions ezihambisanayo ("ukubonisa ukuthi umhla akuyona engahleli") ku-contracts ezihambisanayo. @param {string} date @param {string} date - ISO 8601 format (YYYY-MM-DD). Throws ValidationError if past date. Parameter Constraints Error Handling I-Bus Factor Insurance Waze isigaba akuyona kuphela ukulungiswa kwegama le-function. It inikeza "Ukuhlaziywa kwe-High-Level of Purpose." Lokhu kuyinto isixhumanisi ukuthi uDave waya naye ku-goat farm. It inikeza Futhi, akuyona kuphela . Overview Yini Yini Hlola inkulumo, akuyona inkulumo Ukukhuthaza ikhodi elidokumented, ungenza isikhathi; ungenza umphakeli ukuthi self yakho elizayo (noma abalandeli akho abalandeli) uzodlala ngempumelelo eningi. You don't need to love writing docs. You just need to be smart enough to let a professional ukuhlala. Copy the prompt. Hlola ikhodi. Hlola ithimba. Ngenxa "Dave" kuyoba ukugcina ekupheleni. Qinisekisa ukuthi wahlala emzimbeni yakhe emzimbeni.
