CRySoL

this

related

recent

Cómo escribir una receta

Este documento define las normas de estilo que se deben aplicar a las recetas de la web de CRySoL. Se describe la estructura, el formato y típografía a utilizar. Esta receta sigue las normas que en ella se definen y sirve además como introducción a los formatos de entrada necesarios para poder escribir recetas.

¿Qué es una receta?

Una receta es un documento corto (2 o 3 páginas) cuyo fin es describir un procedimiento o técnica de forma directa y práctica, evitando ornamentos literarios. Es una versión aún más reducida de los llamados mini-howto's ya que ni siquiera se espera que una receta incluya una explicación técnica detallada de cada acción. Utiliza segunda persona del singular (tú, usted) para referirte al lector, preferiblemente el IMPERATIVO, como por ejemplo "copia el fichero en tu home". De ese modo resulta más directo y claro. Evita las formas plurales, como "ahora copiamos el fichero en nuestro home", que pueden ser confusas o ambiguas en muchos casos (no hay "homes" colectivos). Y aunque no tendría ni que pedirse, el único requisito imprescindible e inexcusable es el de respetar escrupulosamente la ortografía y la gramática. Tus lectores y sobre todo los editores te lo agradecerán infinitamente.

Estructura del documento

Ya hemos hablado anteriormente en otros artículos de la conveniencia de fijar unas normas mínimas para el formato de las recetas. En esta primera recetas vamos a concretar las más importantes. Las parte básicas de una receta son:
  1. Título:

    El título de la receta debe ser una frase que describa la utilidad de la misma de forma directa y consisa. Recordad que el título se rellena en un campo del formulario diferente del cuerpo, por lo que no tiene ningún tipo de estilo.

  2. Resumen:

    Es lo primero que debe aparecer en el cuerpo del documento. El resumen es un párrafo que explica con más detalle cuál es la utilidad de la receta. Se trata de que el lector no pierda tiempo leyendola si no es eso lo que está buscando realmente.

  3. Contenido:

    Dado el objetivo de una receta, resulta muy conveniente dividir el documento en tantos puntos(secciones y subsecciones) como pasos implique la realización del procediemiento que se describe.

    Como el criterio principal de las recetas es siempre el tamaño, en lugar de incluir explicaciones detalladas, se aconseja añadir un apartado de referencias para que el lector pueda profundizar en el tema si lo desea.

Formato

Los "formatos de entrada" soportados actualmente para las recetas de CRySoL son:
  • HTML
  • Textile
A continuación se describe para cada uno de ellos la forma de escribir cada uno de los elementos que pueden formar una receta.

Resumen 

Texto del resumen
<!--break-->

Resultado:

El primer párrafo de este documento es un buen ejemplo de cómo queda.

Secciones

  • HTML 
    <h2>Título de la sección</h2>
  • Textile 
    h2. Título de la sección

Resultado:

El título "Formato" de esta misma sección.

Inclusión de ficheros y terminales

Para mostrar fragmentos de un fichero, como puede ser configuración o código fuente, y también para comandos escritos en una consola y el resultado de los mismos ver la receta Listados de código en CRySoL

Listas sin orden

  • HTML 
    <ul>
  <li> tal </li>
  <li> cual </li>
  <li> pascual </li>
</ul>
  • Textile 
    * tal
* cual
* pascual

Resultado:

  • tal
  • cual
  • pascual

Listas ordenadas

  • HTML 
    <ol>
  <li> tal </li>
  <li> cual </li>
  <li> pascual </li>
</ol>
  • Textile 
    # tal
# cual
# pascual

Resultado:

  1. tal
  2. cual
  3. pascual

Enlaces

  • HTML 
    The <a href="http://gnu.org">GNU</a> Operating System
  • Textile 
    The "GNU":http://gnu.org Operating System

Resultado:

The GNU Operating System

Otras cuestiones de estilo

Se debe utilizar:
  • negrita para los términos relevantes: <b>html</b> y *textile*
  • cursiva para palabras en un idioma extranjero o conceptos ámplios: <em>html</em> y _textile_
  • monoespacio para nombres de ficheros y comandos: <code>html</code> y @textile@

Añadir imágenes

Como lo de las imágenes es una cuestión peliaguda, los usuarios normales no pueden usar el elemento <img> ni subir adjuntos. Cuando hayas demostrado que eres "persona de bien" puedes pedir a un administrador que te dé permisos para ambas cosas. Suponiendo que ya tienes permiso debes seguir estos pasos.
  1. Escribe un mínimo de la receta, por ejemplo la introducción y envíala sin publicarla. Ahora verás que tu post queda identificado con un número en la URL, algo como: crysol.org/node/*1504*.
  2. Renombra las imágenes que quieras subir a tu receta para que empiecen con ese número, seguido de un guión bajo. Por ejemplo: *1504_pantallazo1.png*.
  3. Ahora edita tu receta y en la sección "Archivos adjuntos" sube añade cada una de tus imágenes. Una vez que las hayas subido, serán accesibles desde el directorio @files@, por ejemplo: crysol.org/files/1504_pantallazo1.png
  4. Y ya sólo te queda enlazarlas en el cuerpo de tu receta. No pongas URL absolutas (a menos que enlaces algo externo) porque este portal tiene varios nombres DNS. Utiliza rutas relativas, es decir: 
        <img src="/files/crysol_logo.gif"/>

Cómo enviar una receta

Todos los usuarios registrados en la web pueden escribir "entradas" en su bitácora(blog), así que:
  • Para escribir una receta, debes escribir una entrada en su blog siguiendo el formato indicado en esta receta.
  • Etiqueta dicha entrada de blog como "receta" en la lista "tipo de nodo", que aparece justo encima del cuerpo del documento. Opcionalmente elige uno o varios de la lista de "temas".
  • Como autor, quedas a cargo del mantenimiento de la receta, lo cual incluye responder los comentarios que se hagan (en la medida de tus posibilidades), arreglar errores e incorporar mejoras.
blog comments powered by Disqus