GuiaPublicacionArticulos

De Yii Framework en Español (Yiiñ)

Contenido

Guía Para Publicar Artículos

En la presente guía se indicarán las condiciones para que un artículo sea aprobado sin enmiendas, subsecuentes correcciones ni rechazos. Un consejo importante: Se honesto, haz un compromiso genuino con esta wiki, y sé generoso. Lée la guía aunque sea aburrida. Todos estaremos agradecidos. Incluso tú.

¿Por qué una guía?

Quizá sea un poco antipático ajustarse a una "formalidad" como esta pero las razones son simples:

  • Homogeneidad: si todos nos ajustamos a un mismo "formato" para los correctores y los lectores será mucho más sencillo encontrar detalles que pueden convertir tu publicación en un referente...
  • Eficacia: nuevamente, los lectores (tu principal público), ya sabrán dónde mirar lo que les interesa; les ahorrarás tiempo, y estructurarás la información de tal modo que sepan cuando y cuando no buscar más detalles en lo que publicas...
  • Eficiencia: el tiempo vale oro cuando estamos detrás de un problema, y todos fuimos víctimas de peroratas extensas para solo decir "Hola Mundo" y saber que "eso" no era o que buscábamos...
  • Calidad: ¿hace falta que aclaremos este punto?...

Tipos de Guías

Hasta ahora imaginamos estos tipos de guías posibles:

  • Documentación: detalle de una extensión, módulo, widget, componente (propio o de terceros)...
  • Traducciones: de otros sitios en otros idiomas, de la documentación oficial, etc...
  • Informes Blancos, white papers...
  • Trucos y Pistas (o consejos prácticos, tips & hints)...
  • Casos de estudio...
  • Referencias teóricas (basadas en el concepto Yii)...
  • Guías en vídeo (videotutoriales)...

Y algunas más que pronto iremos poniendo según vayan apareciendo.

Cómo escribir en esta Wiki

Es más que obvio que un lenguaje moderado es más que pretendido, el respeto hacia el género, creencia, raza o cualquier otra forma que agreda de alguna forma nimia será censurada. Está de más indicarlo, pero un poco de Netiqueta no está de más.

Hay un refrán popular que reza "No rizar el rizo", es un buen momento de echarle mano y tomar debido conocimiento de cómo se da "formato" a los textos (lo tuve que usar y aprender para escribir lo que estás leyendo... Es útil, créelo) Aquí está explicado al detalle.

Otro punto importante es que el "castellano" o "español" (como gustes, de ahora en más prefiero decir castellano) es muy rico para "re fritar" términos... Por favor, en la medida de lo posible, usa términos aprobados por la RAE, busca las traducciones aprobadas en WordReference, o cualquier otro sitio de tu gusto para que todos entendamos si no sabemos de que se trata.

Recuerda "por qué" estás en un sitio técnico en castellano: te aburriste de pensar en otro idioma...

Piensa siempre que el "otro" eres tú; entonces, imagina que no sabes de qué hablas y quieres entender. Sé claro, aunque parezca claro y obvio lo que expones. Otro refrán me viene a la memoria y dice: "No existen preguntas tontas, sólo respuestas"... Tenlo presente.

Por último, y no menos importante, quien escribe estas líneas no está acostumbrado a un castellano neutro. Respeta su esfuerzo, y de los que colaboran usando una forma neutra para ser bien entendido. Evita regionalismos, lunfardos o slangs por más bien entendidos que sean. Por ejemplo coger no siempre se entiende como tomar o asir.

Cómo escribir las Guías

Lineamientos Generales

Toda guía debe tener un Objetivo, una hipótesis, un desarrollo y un desenlace.

Es decir, contar una historia del tipo: tuve este problema, me lo planteé de este modo, luego de varios intentos lo resolví de esta manera.

A nadie le sirve un "hola mundo"... ¿somos claros?...

Por otro lado, son bienvenidas las traducciones o adaptaciones o mejoras de otras guías, pero tienen un autor. De ser ése el caso, nombrar la fuente, en lo posible contactar al autor y decirle Voy a adaptar tu caso, para Yii Framework en Español... o como quieras adaptarlo a tu forma... Él dedicó tiempo y debe saberlo.

Empezaremos con los detalles:

Documentación

  • Nombrar la fuente
  • Adaptar el texto a esta guía
  • Mejorar el original, o al menos igualar su calidad

Traducciones

  • Lo antedicho en Documentación
  • Informar a la fuente de la cita
  • Indicar el texto fuente

Informes Blancos

  • Interiorizarse de que se trata
  • Son casos "teóricos" con fines prácticos
  • No sirve para su "solución" un "hola mundo!"
  • Es un ejemplo de un caso personal, que se resolvió de manera eficiente, eficaz; un paradigma
  • Tiene estructura de teorema: Tesis, hipótesis, solución...
  • Llegado el caso: axioma o corolario

Trucos y Pistas

  • Son simples textos que de un vistazo resuelven un problema común
  • No exceden las 5 líneas de explicación del problema
  • Son específicos en cuanto al código, directos al punto del problema

Casos de Estudio

  • Son casos "teóricos", que pueden no incluir código
  • Invitan a discutir y reflexionar sobre un aspecto técnico y profundo
  • Puede derivar en cualquiera de los puntos mencionados para su solución o implementación práctica

Referencias Teóricas

  • Similar al punto anterior, con la diferencia que es una adaptación, traducción o ampliación de un texto ya existente en la red
  • Por tener, quizá, ya un autor y aportar su adaptación, considerar la referencia a él, su fuente, etc.

Guías en Vídeo

  • El vídeo es "el dictado de la materia", el que explica "todo" lo referente a ese tema a exponer. Pero no siempre se cuenta con el tiempo o los recursos técnicos para poder disfrutarlo, por ello...
  • Proveer un texto a modo de "apunte" o "notas" que cubran el tema, de modo que se pueda identificar de inmediato si responde a la inquietud y enfocarse en lo relevante del mismo. Quien lo necesite verá el vídeo completo, el que no refrescará o identificará su respuesta de inmediato
  • Incluir el código importante para facilitar su "pegado y copiado" y evitar errores de tipeo
  • Sería ideal incluir, cuando sea oportuno, un "sitio base" con la aplicación práctica de lo explicado, con su código explicado lo más posible para poder seguir el vídeo
En breve este artículo será ampliado.
Siguiente tema a desarrollar: Formato de una guía
Herramientas personales