Módulo de documentación y ayuda

Algunos módulos en realidad no requieren que hagas nada, simplemente hacen lo que hacen entre bastidores. Sin embargo, estos módulos probablemente no tienen configuraciones personalizables o solo sirven como dependencias para otros módulos.

La mayoría de las veces, el módulo que te interesa es aquel para el que puedes configurar permisos y ajustes. Algunos proyectos son fáciles de usar, es decir, su uso es "intuitivo", y te quedará relativamente claro qué puedes configurar y qué necesitas hacer para lograr lo que quieres.

Si deseas conocer todos los detalles necesarios para usar inteligentemente un módulo que acabas de instalar, puedo sugerirte algunas cosas que podrías necesitar o lugares donde buscar.

Las siguientes sugerencias están ordenadas según su facilidad de uso.

Desafortunadamente para usuarios finales principiantes como nosotros, Drupal está en constante evolución, y aunque tenemos la suerte de beneficiarnos de todo el enorme trabajo de los desarrolladores, su tiempo es limitado, y creo que se puede decir con seguridad que los mejores desarrolladores no suelen ser los creadores más diligentes de documentación para principiantes como nosotros; de lo contrario, tú y yo no estaríamos aquí ahora.

Te aconsejaría que documentes y publiques tus pruebas y dificultades mientras aprendes a usar Drupal, para el beneficio de miles de personas que estarán en tu lugar en los próximos días, meses y años.

Asumo esto como el reto final para crear esta documentación, a pesar de (o debido a) las aparentemente interminables irritaciones, frustraciones y tensiones — el uso de una nueva sección de documentación en Drupal — y, en menor medida, para evitar problemas de aprendizaje y uso de Drupal que podrían haberse resuelto si otros principiantes, como tú y yo, hubieran creado previamente instrucciones adecuadas para principiantes; pero sobre todo me alegra que tú, amigo mío, te beneficies de ello.

No necesitas saber nada sobre "desarrollo" o programación para compartir lo que "sabes" y has aprendido.

Método de prueba y error

Puedes simplemente lanzarte y empezar a usar el módulo o a experimentar con sus configuraciones.

En los casos en que, tras investigar, no entiendas qué hace una opción o cuáles podrían ser todas las posibles consecuencias de usarla, simplemente puedes probar todo lo que tu espíritu aventurero considere mejor.

Siempre que llegues a un punto donde el módulo requiera conjeturas de tu parte, realmente no necesitas preocuparte por probar cualquier opción disponible, porque hacer una copia de seguridad de tu sitio siempre te ayudará a volver a una versión anterior. ¿Haces copias de seguridad de tu sitio, verdad?

Dado que puede no ser obvio de inmediato para ti que todos los efectos causados por el módulo o una opción específica estarán presentes en tu sitio, por esta razón te recomiendo probar un módulo a la vez y explorar cada rincón de tu sitio intentando usarlo de todas las formas posibles — crear nuevas páginas y probar diferentes configuraciones — antes de añadir otro módulo contrib.

De lo contrario, si activas más de un módulo nuevo y luego encuentras problemas o situaciones que te parecen extrañas, no sabrás cuál de los nuevos módulos es responsable de lo que te preocupa.

Contenido de la página del proyecto

Cada página de proyecto de un módulo es su página principal en drupal.org. Normalmente, entro a la página del proyecto primero cuando pienso si vale la pena probar un módulo, o cuando tengo problemas o preguntas sobre un módulo que acabo de activar.

Si lees cuidadosamente la página del proyecto en su totalidad, puedes estar relativamente seguro de que tienes toda la información importante que necesitas. Por ejemplo, al considerar si probar un módulo, si el módulo requiere otros módulos para funcionar, estos estarán listados en algún lugar de la página del proyecto.

La página del proyecto también puede contener otros enlaces útiles relacionados con muchas cosas sobre ese módulo.

El contenido de la página del proyecto puede estar dirigido a usuarios nuevos de Drupal o a usuarios más avanzados / desarrolladores.

Enlace "Leer documentación" en la página del proyecto (si existe)

En la columna derecha (la columna que baja hasta la parte inferior de la página en dispositivos móviles o en otras ventanas estrechas del navegador) siempre encontrarás el título "Recursos", bajo el cual puedes o no encontrar un enlace "Leer documentación".

Sin embargo, no todas las páginas de proyectos tienen un enlace "Leer documentación" y, en ese caso, esperemos que encuentres enlaces útiles a documentación en el área principal de contenido de la página del proyecto.

Cuando existe el enlace "Leer documentación", será lo que los desarrolladores consideran el recurso más adecuado para que comiences a buscar información adicional.

El contenido de cada página del proyecto está definido y controlado por el creador original de ese proyecto y posiblemente por algunas otras personas a quienes el creador original les haya dado permiso.

Otros miembros de drupal.org, sin acceso para modificar la página del proyecto, a menudo crean otras páginas en d.o con excelente información sobre el módulo que te interesa. Lamentablemente, estas otras páginas rara vez estarán enlazadas desde la página del proyecto.

La búsqueda de esas páginas no enlazadas se tratará más abajo en la sección de búsqueda Google limitado a drupal.org ⤵

Archivo README.txt del módulo

Históricamente, el archivo "README.txt" ha sido el lugar oficial donde se documenta toda la información realmente importante y necesaria para un módulo (o tema), incluyendo todo lo relacionado con actualizar el módulo (o tema) a una versión más nueva.

El archivo README.txt se encuentra en la carpeta de nivel superior del módulo contrib (o tema) después de descomprimirlo, si existe.

Para ver el archivo README.txt de un módulo (o tema) sin descargar nada, visita el siguiente enlace:

http://cgit.drupalcode.org/project/PROJECT_MACHINE_NAME.git/blob/HEAD:/README.txt

Sustituye la expresión PROJECT_MACHINE_NAME en la URL anterior por el "nombre de máquina" corto del proyecto específico.

El "nombre de máquina" está en la URL de la barra de direcciones de tu navegador cuando estás en cualquier página de proyecto en drupal.org, como la parte "PROJECT_MACHINE_NAME" en este ejemplo de URL — una URL similar para cada proyecto:

https://www.drupal.org/project/PROJECT_MACHINE_NAME

Si no existe el archivo README.txt, probablemente sea un módulo sin configuraciones personalizadas y que simplemente funciona en segundo plano y es necesario para que otros módulos contrib funcionen.

Si no hay README.txt o simplemente quieres ver toda la documentación restante para el proyecto, usa la siguiente URL (sustituye "PROJECT_MACHINE_NAME"):

http://cgit.drupalcode.org/PROJECT_MACHINE_NAME/tree/?id=HEAD

En la esquina superior derecha de esta página "drupalcode.org" puede que tengas que "cambiar" a la versión del núcleo de Drupal que deseas examinar.

Búsqueda en Google limitada a drupal.org

Si quieres que la búsqueda esté limitada a todo el sitio drupal.org, esto es lo que hago. Uso este método con bastante frecuencia para buscar en drupal.org o en cualquier otro dominio que elija.

Voy a google.com ⎘ y escribo:

site:drupal.org

Nota que no hay espacio después de los dos puntos (":") antes del nombre de dominio. Tampoco uses "www." al inicio del dominio.

Agrega un espacio después del nombre de dominio y escribe las palabras clave que se te ocurran, en nuestro caso, el nombre del módulo.

A veces también encuentro útil tratar de limitar la búsqueda de Google específicamente a "Drupal 8" (en lugar de obtener también resultados para D6, D7...), añadiendo "Drupal 8" en el campo de texto de búsqueda de Google. Usando comillas dobles, Google devolverá resultados para páginas que contengan esa expresión exacta de dos o más palabras entre comillas. (...principalmente.)

Para ver qué información está disponible para un módulo específico en todo el mundo, incluyendo páginas dentro y fuera de drupal.org, omite site:drupal.org.

Para obtener 100 resultados en la página de Google en lugar de 10, cuando estés en cualquier página de resultados de Google, haz clic en el icono de "engranaje" en la esquina superior derecha y en el menú desplegable selecciona "Configuración de búsqueda". En la página siguiente, bajo "Predicciones instantáneas de Google", selecciona "Nunca mostrar resultados instantáneos". Luego, bajo "Resultados por página", mueve el control deslizante completamente a la derecha. Tus búsquedas ahora tomarán unas milésimas de segundo más o menos.

Opinión personal: podrías pensar en usar el motor de búsqueda provisto por drupal.org en la parte superior de todas sus páginas. Lo he probado varias veces y te aconsejaría que lo pruebes tú mismo solo si te gustan los ejercicios inútiles.

Botones/enlaces de "Ayuda" en la página "Extender" de tu sitio (si están disponibles)

En la página "Extender" de tu sitio, a la derecha del nombre de cada módulo, puedes ver la primera línea de su descripción si la ventana de tu navegador es suficientemente ancha.

Si haces clic en esa primera línea de descripción, se desplegará hacia abajo y mostrará el resto de su descripción, además de mostrar botones/enlaces de "Ayuda", "Permisos" y "Configurar" para ese módulo cuando esos elementos estén disponibles.

Si no ves inmediatamente la primera línea de descripción del módulo a la derecha de su nombre y quieres verla, sigue las instrucciones en la página de configuración del módulo.

Desafortunadamente, para acceder a la página de ayuda en tu sitio para un módulo, no solo debes importar el módulo a tu sitio, sino que el botón/enlace "Ayuda" solo será visible si ese módulo está habilitado. Y, lamentablemente, no todos los módulos contrib o del núcleo tienen un botón/enlace "Ayuda", así que no sabrás si está disponible a menos que actives primero el módulo.

Por estas razones problemáticas, nunca he confiado ni usado los botones de "Ayuda", aunque al mirarlos ahora veo que a menudo conducen a páginas con información útil.