Objetivo

Presentar y explicar en un archivo de texto de fácil acceso el propósito del proyecto, con información sobre cómo instalar, utilizar o también sobre cómo colaborar.

Directrices

  • Debe estar en el directorio raíz del software donde aplica.
  • Debería ser el primer archivo a crear en un proyecto.
  • Se recomienda el nombre README.md y usar Markdown.

Apartados

Tabla de contenidos

  • Table of contents (Opcional)
  • Se agradece en archivos README largos.

Introducción

  • Introduction (Requerido)
  • Uno o dos párrafos breves que resuman el propósito y la función del proyecto.
  • Describir las funcionalidades, el contexto y los problemas de desarrollo que ayudó a resolver.
  • Incluir enlaces a la página del proyecto y a los sitios donde los usuarios pueden encontrar ayuda, ya sea un gestor de incidencias, un manual de uso, foros, una dirección de correo electrónico, un chat, etc…
  • Puede utilizarse la misma introducción en la página del proyecto.

Requerimientos

  • Requirements (Requerido)
  • Enumerar todo lo necesario para obtenerlo e incluirlo antes de instalar el proyecto.
  • Si no hay requisitos, escribir «No hay requisitos especiales» («No special requirements«).

Recomendado

  • Recommended (Opcional)
  • Enumerar los requisitos que no son necesarios pero que pueden mejorar la utilidad o la experiencia de uso del proyecto.

Instalar

  • Installation (Requerido)
  • Puede proporcionarse en un archivo INSTALL separado si las instrucciones de instalación son especialmente complejas.
  • Enumerar claramente los pasos para instalar el software.

Actualizar

  • Upgrade (Opcional)
  • Puede proporcionarse en un archivo UPGRADE separado si las instrucciones de actualización son especialmente complejas.
  • Enumerar claramente los pasos para actualizar el software.

Configuración

  • Configuration (Opcional)
  • Enumerar las opciones de configuración, incluyendo, entre otros aspectos, los permisos de uso.

Solución de problemas

  • Troubleshooting (Opcional).
  • Describir los problemas comunes que los usuarios encuentran junto con las soluciones aportadas.
  • Los enlaces están bien si los pasos son largos, pero es útil proporcionar un resumen para sortear enlaces obsoletos.

Preguntas frecuentes

  • FAQ (Opcional)
  • Incluir las preguntas que se hacen con frecuencia en el gestor de incidencias y las respuestas habituales.

Mantenedores

  • Maintainers (Opcional)
  • Puede proporcionarse en un archivo MAINTAINERS separado.
  • Créditos a los creadores, mantenedores y colaboradores.
  • Reconocimientos a personas u organizaciones que hayan contribuido, patrocinado o apoyado de alguna forma al proyecto.

Cómo contribuir

  • Contributing (Opcional)
  • Puede proporcionarse en un archivo CONTRIBUTING separado.
  • Indicar si el proyecto está abierto a contribuciones y cuáles son los requisitos para aceptarlas.

Código de conducta

  • Code of conduct (Opcional)
  • Puede proporcionarse en un archivo CODE_OF_CONDUCT separado.
  • Establece las normas sociales, reglas y responsabilidades que los individuos y organizaciones deben seguir para participar en el proyecto o su comunidad.
  • Es una buena práctica para crear un ambiente de respeto e inclusión en las contribuciones al proyecto.

Licencia

  • License (Opcional)
  • Puede proporcionarse en un archivo LICENSE separado.
  • Establece los derechos que se otorgan a terceros.

Buenas prácticas

  • Evitar siempre que sea posible las líneas con más de 80 caracteres.
  • Usar ejemplos de uso con generosidad, proporcionando enlaces a ejemplos más sofisticados si son demasiado largos para este archivo.

Ejemplo de README.md

Original: https://www.drupal.org/docs/develop/documenting-your-project/readme-template

# README

## CONTENTS OF THIS FILE
   
* Introduction
* Requirements
* Recommended
* Installation
* Configuration
* Troubleshooting
* FAQ
* Maintainers


## INTRODUCTION

The Administration Menu module displays the entire administrative menu tree
(and most local tasks) in a drop-down menu, providing administrators one- or
two-click access to most pages.  Other modules may also add menu links to the
menu using hook_admin_menu_output_alter().

* For a full description of the module, visit the project page:
  https://www.drupal.org/project/admin_menu

* To submit bug reports and feature suggestions, or track changes:
  https://www.drupal.org/project/issues/admin_menu


## REQUIREMENTS

This module requires the following modules:

* Views (https://www.drupal.org/project/views)
* Panels (https://www.drupal.org/project/panels)


## RECOMMENDED

* Markdown filter (https://www.drupal.org/project/markdown):
  When enabled, display of the project's README.md help will be rendered
  with markdown.


## INSTALLATION
 
* Install as you would normally install a contributed Drupal module. Visit
  https://www.drupal.org/documentation/install/modules-themes/modules-7 for
  further information.

* You may want to disable Toolbar module, since its output clashes with
  Administration Menu.


## CONFIGURATION
 
* Configure the user permissions in Administration » People » Permissions:

  - Use the administration pages and help (System module)

    The top-level administration categories require this permission to be
    accessible. The administration menu will be empty unless this permission
    is granted.

  - Access administration menu

    Users with this permission will see the administration menu at the top of
    each page.

  - Display Drupal links

    Users with this permission will receive links to drupal.org issue queues for
    all enabled contributed modules. The issue queue links appear under the
    administration menu icon.

* Customize the menu settings in Administration » Configuration and modules »
  Administration » Administration menu.

* To prevent administrative menu items from appearing twice, you may hide the
  "Management" menu block.


## CONFIGURATION

The module has no menu or modifiable settings. There is no configuration. When
enabled, the module will prevent the links from appearing. To get the links
back, disable the module and clear caches.


## TROUBLESHOOTING

* If the menu does not display, check the following:

  - Are the "Access administration menu" and "Use the administration pages and
    help" permissions enabled for the appropriate roles?

  - Does HTML.tpl.php of your theme output the $page_bottom variable?


## FAQ

Q: I enabled "Aggregate and compress CSS files", but admin_menu.CSS is still
   there. Is this normal?

A: Yes, this is the intended behavior. the administration menu module only loads
   its stylesheet as needed (i.e., on page requests by logged-on, administrative
   users).


## MAINTAINERS

Current maintainers:

* Daniel F. Kudwien (sun) - https://www.drupal.org/user/54136
* Peter Wolanin (pwolanin) - https://www.drupal.org/user/49851
* Stefan M. Kudwien (smk-ka) - https://www.drupal.org/user/48898
* Dave Reid (Dave Reid) - https://www.drupal.org/user/53892

This project has been sponsored by:

* UNLEASHED MIND
  Specialized in consulting and planning of Drupal powered sites, UNLEASHED MIND
  offers installation, development, theming, customization, and hosting to get
  you started. Visit https://www.unleashedmind.com for more information.

Última revisión: 28/06/2020

0 comentarios

Dejar un comentario

¿Quieres unirte a la conversación?
Siéntete libre de contribuir!

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *