No fue un hacker el que derribó nuestra puerta de pago el año pasado.No fue un ataque DDoS o una fuga de memoria. Era el Dave. Bueno, específicamente, fue el hecho de que Dave decidió mudarse a una granja de cabras en Vermont, dejando atrás 15.000 líneas de código de spaghetti que manejaban toda nuestra lógica de facturación recurrente. Encontré este comentario útil: BillingService.js // TODO: Fix this hack later. It's ugly but it works. - Dave, 2019 No hay definiciones de parámetros. No hay tipos de retorno. No hay explicación de por qué la línea 405 estaba dividida por una variable llamada Pasamos tres días en ingeniería inversa de nuestro propio producto mientras los clientes se burlaban. magicNumber Tratamos la documentación del código como el flossing: sabemos que Si lo hacemos, mentimos a nuestros dentistas (managers) acerca de hacerlo, pero en realidad lo hacemos sólo cuando las cosas comienzan a arruinarse. Debe ¿Y si pudieras tener un Escritor Técnico con 10 años de experiencia sentado a tu lado, convirtiendo tus scripts de Python criptográficos en documentación primitiva, lista para Sphinx en segundos? He dejado de esperar que los desarrolladores sean poetas. . Agentic Documentation Strategy La epidemia de base de códigos "sólo escrita" La mayoría de la documentación generada por la IA es fluida.Le pedimos a ChatGPT que "documente esto", y le da: def process_data(data): """ Processes the data. """ Gracias Robot, es muy útil. La documentación real necesita responder a las preguntas que te mantienen despierto por la noche: ¿Qué ocurre si esta entrada es nula? ¿Por qué depende esta función de una variable global? ¿Cuál es el formato específico del objeto de devolución? Para obtener nivel de detalle, tienes que forzar a la IA a pensar como un mantenedor, no como un resumidor. que obliga al LLM a analizar el del código, no sólo de la sintaxis. que Code Documentation System Prompt Intención El Sistema de Escritor Técnico Prompt Pongo este prompt en Claude o ChatGPT, descargo mi función y recupero la documentación que parece pertenecer a una biblioteca mantenida por Google. Hazlo parte de tu lista de verificación de PR. 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 Por qué esto funciona (Cuando "Please Document This" falla) Esta prompt funciona porque cambia el "modelo mental" de la IA de un chateador casual a un archivista riguroso. El mandato “Ejemplo de uso” Mira el El punto: La documentación te dice El código no. Los ejemplos te dicen Al forzar a la IA a generar un ejemplo de trabajo, se resuelve el 80% de las preguntas "¿cómo llamo esto?" antes de que se pidan. Quality Checklist Se proporciona al menos un ejemplo de uso Qué Cómo Extracción de Edge Case A Junior Dev escribe: Esta prompt obliga a la AI a escribir: Exigimos explícitamente y Transforma suposiciones implícitas ("obviamente la fecha no puede ser nula") en contratos explícitos. @param {string} date @param {string} date - ISO 8601 format (YYYY-MM-DD). Throws ValidationError if past date. Parameter Constraints Error Handling El seguro “Bus Factor” El La sección no es sólo una reposición del nombre de la función. Requiere un "resumen de propósito de alto nivel." Este es el contexto que Dave llevó con él a la granja de cabras. No sólo el . Overview por qué Qué Deja un legado, no un misterio Cuando empujas el código sin documentos, no ahorras tiempo; estás tomando un préstamo que tu futuro yo (o tus pobres compañeros de equipo) tendrán que pagar con un interés masivo. Usted no tiene que amar la escritura de documentos. sólo tiene que ser lo suficientemente inteligente como para dejar que un especialista lo maneje. Copie el prompt. Póngase el código. Guardar el equipo. Porque "Dave" va a dejar finalmente. asegúrese de que deje su cerebro atrás.
