Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Directrices de contenido

This document outlines what should be included in the official documentation. Below, you will find a couple of principles and recommendations for writing accessible content.

Nosotros queremos alcanzar dos metas:

  1. Empatiza con nuestros usuarios. Debemos escribir de una manera que les facilite aprender de la documentación.

  2. Write a complete reference manual. Our goal here is not to teach programming fundamentals. Instead, our goal is to provide a reference for how Godot's features work.

Directrices y principios

Below are the guidelines we should strive to follow. They are not hard rules, though: sometimes, a topic will require breaking one or more of them. Still, we should strive to achieve the two goals listed above.

Escribir documentación completa y accesible

Una característica no existe a menos que esté documentada. Si un usuario no puede encontrar información sobre una característica y cómo funciona, para ellos esa característica no existe. Debemos asegurarnos de cubrir todo lo que hace Godot.

Nota

Cuando se agrega o actualiza una característica del motor, el equipo de documentación necesita estar informado al respecto. Los colaboradores deben abrir un issue en el repositorio godot-docs cuando su trabajo se haya fusionado y requiera documentación.

Do your best to keep documents under 1000 words in length. If a page goes past that threshold, consider splitting it into two parts. Limiting page size forces us to write concisely and to break up large documents so that each page focuses on a particular problem.

Each page or section of a page should clearly state what problem it tackles and what it will teach the user. Users need to know if they're reading the correct guide for solving the problems they're encountering. For example, instead of writing the heading "Signals", consider writing "Reacting to changes with signals". The second title makes it clear what the purpose of signals is.

Nota

Los títulos de sección largos resultan en entradas largas en el menú lateral, lo que puede dificultar la navegación. Trata de mantener los encabezados con un máximo de cinco palabras o menos.

If the page assumes specific knowledge of other Godot features, mention it and link to the corresponding documentation. For instance, a page about physics may use signals, in which case you could note that the signals tutorial is a prerequisite. You may also link to other websites for prerequisites beyond the documentation's scope. For example, you could link to an introduction to programming in the getting started guide, or a website that teaches math theory in the math section.

Limitar la carga cognitiva

Limitar la carga cognitiva requerida para leer la documentación. Cuanto más simple y explícito sea el lenguaje que utilizamos, más eficiente será para que las personas aprendan. Puedes lograrlo mediante:

  1. Introducir solo un nuevo concepto a la vez siempre que sea posible.

  2. Usar un inglés simple, como recomendamos en nuestras pautas de escritura.

  3. Including one or more concrete usage examples. Prefer a real-world example to one that uses names like foo, bar, or baz.

While many people may understand more complex language and abstract examples, you will lose others. Understandable writing and practical examples benefit everyone.

Always make an effort to put yourself in the user's shoes. When we understand something thoroughly, it becomes obvious to us. We may fail to think about details relevant to a newcomer, but good documentation meets users where they are. We should explain each feature's capabilities or intended uses with the most straightforward language possible.

Trata de recordar lo que necesitaste saber cuando aprendías sobre la característica o el concepto por primera vez. ¿Qué términos nuevos necesitaste aprender? ¿Qué te confundió? ¿Qué fue lo más difícil de comprender? Querrás que los usuarios revisen tu trabajo, y te recomendamos practicar explicar la característica antes de escribir sobre ella.

Nota

Programming fundamentals are a prerequisite for using a complex engine like Godot. Talking about variables, functions, or classes is acceptable. But we should favor plain language over specific terminology like "metaprogramming". If you need to use precise terms, be sure to define them.