Het was geen DDoS-aanval of geheugenlek. Het was Dave. Welnu, specifiek, het was het feit dat Dave besloot om naar een geitenboerderij in Vermont te verhuizen, waardoor er 15.000 rijen spaghetti-code achterkwam die onze hele recidiverende factureringslogica behandelde. Ik vond dit nuttige commentaar: BillingService.js // TODO: Fix this hack later. It's ugly but it works. - Dave, 2019 Dat was het. geen parameterdefinities. geen retourtypen. geen verklaring waarom lijn 405 werd verdeeld door een variabele genaamd We brachten drie dagen door met omgekeerde engineering van ons eigen product, terwijl de klanten struikelden. magicNumber We behandelen code documentatie als flossing: we weten dat we Als we het doen, liegen we tegen onze tandartsen (managers) over het doen, maar we doen het alleen echt als de dingen beginnen te rotten. moet Wat als je een Technical Writer met 10 jaar ervaring naast je zou kunnen hebben, je cryptische Python-scripts in seconden in ongebruikelijke, Sphinx-klare documentatie zou kunnen veranderen? Ik stopte met verwachten dat ontwikkelaars dichters zouden zijn. . Agentic Documentation Strategy De ‘Write-Only’ Codebase Epidemie Je vraagt ChatGPT om dit te "documenteren", en het geeft je: def process_data(data): """ Processes the data. """ Bedankt Robot, zeer behulpzaam Echte documentatie moet antwoorden op de vragen die je 's nachts wakker houden: Wat gebeurt er als deze input null is? Waarom is deze functie afhankelijk van een globale variabele? Twee krijgen niveau van detail, je moet de AI dwingen om te denken als een onderhoudsmanager, niet een samenvatting. Dit dwingt de LLM om de van de code, niet alleen de syntax. dat Code Documentation System Prompt Intentie Het technische schrijversysteem prompt Ik plak deze prompt in Claude of ChatGPT, drop in mijn functie en krijg documentatie terug die lijkt te behoren tot een bibliotheek onderhouden door Google. Maak het onderdeel van je PR checklist. 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 Waarom dit werkt (Wanneer "Please Document This" mislukt) Deze prompt werkt omdat het het "mentale model" van de AI verandert van een casual chatter naar een rigoureuze archivist. Het "gebruik voorbeeld" mandaat Kijk naar de Het item: Documentatie vertelt u Code does. Voorbeelden vertellen je Door de AI te dwingen om een werkende voorbeeld te genereren, los je 80% van de "hoe noem ik dit?" vragen op voordat ze zelfs worden gevraagd. Quality Checklist Tenminste één voorbeeld van gebruik wordt verstrekt Wat Hoe 2. edge case opgraving Een junior dev schrijft: Deze prompt dwingt de AI om te schrijven: Het vraagt uitdrukkelijk om en Het verandert impliciete veronderstellingen ("de datum kan duidelijk niet ongeldig zijn") in expliciete contracten. @param {string} date @param {string} date - ISO 8601 format (YYYY-MM-DD). Throws ValidationError if past date. Parameter Constraints Error Handling De “Bus Factor” verzekering De sectie is niet alleen een herstelling van de naam van de functie. Het vereist een "High-level summary of purpose." Dit is de context die Dave met hem naar de geitenboerderij bracht. Niet alleen de . Overview Waarom Wat Laat een erfenis achter, geen mysterie Wanneer je ongedocumenteerde code duwt, bespaar je geen tijd; je neemt een lening uit die je toekomstige zelf (of je arme teamgenoten) met enorme rente zullen moeten terugbetalen. Je hoeft niet van het schrijven van documenten te houden, je hoeft alleen maar slim genoeg te zijn om een specialist ermee te laten omgaan. Kopieer de prompt. Pas de code in. Sla het team op. Omdat "Dave" uiteindelijk zal stoppen. zorg ervoor dat hij zijn hersenen achterlaat.
