Es/Guía de estilo del grupo comunitario de educacion web

From Web Education Community Group
Revision as of 12:56, 8 March 2012 by Nrojas2 (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Pautas de estilo para el Grupo comunitario de educación web del W3C

El material de aprendizaje y los programas de estudio publicados por el Web Education Community Group (Grupo comunitario de educación web) del W3C (en lo sucesivo denominado "WebEdu CG") deben seguir las pautas contenidas en este documento lo más ajustadamente posible para garantizar la calidad y coherencia global. En realidad, algunos de los materiales sólo seguirán vagamente estas pautas. Muchos de ellos se importarán de recursos existentes, como el Currículo de estándares web de Opera, Mozilla Developer Network, Microsoft Developer Network, etc., y no sería un buen el uso de nuestro tiempo dedicarnos a colocarle los puntos a todas las "ies" y colocar las rayitas a todas las "tes" según directrices específicas del idioma. Sin embargo, debemos tratar de seguirlas tanto como sea razonablemente posible.

Lenguaje

A lo largo de nuestro material debemos utilizar un tono informal y coloquial, pero con autoridad. No queremos que el material sea demasiado seco y académico, y no hay nada malo en divertirse un poco e incluir un par de chistes, pero también queremos que el tono refleje conocimiento, autoridad y confianza.

Queremos lograr un equilibrio.

En cuanto a directrices específicas de idioma, no quiero imponer demasiadas, por ejemplo: "Debe usar Inglés de EE.UU." ya que habrá muchos autores diferentes en este proyecto. Pero es bueno tener estas directrices para resolver las dudas, por lo que especificamos:

  • Gramática general - refiérase al Manual de Estilo de Chicago
  • Clasificación general del idioma inglés - Inglés de EE.UU. En particular, esto es útil porque las palabras en inglés que aparecen en la sintaxis del código se escriben en Inglés de EE.UU., así que tener palabras como color escrita consistentemente entre la sintaxis y el texto normal ayudará a reducir la confusión.
  • Comas de lista - coma oxford o serial, ej: uno, dos, y tres, no uno, dos y tres.
  • 1ra persona/3ra persona - use "nosotros"/"usted" en lugar de "yo", al menos que realmente sea un caso que requiera el yo, por ej.: "Yo, el autor, le estoy contando una anécdota personal". Me parece que "nosotros"/"usted" suena más como el autor y los lectores trabajando juntos, como iguales, en lugar del autor contándole a los lectores, lo que puede convertirse en algo un poco paternalista. Una relación entre pares tiene mayor disposición a hacer que los lectores se sientan más a gusto y les haga sentir como una verdadera comunidad.
  • Tiempo - tiene mayor sentido usar el tiempo presente a menos que un tiempo diferente sea más apropiado.
  • Otras formas específicas del lenguaje:
    • RELLENAR MIENTRAS VAN SURGIENDO

Estándares de código

El material debe ser tan de avanzada como sea posible, por lo que utilizaremos las prácticas y técnicas más modernas disponibles en cualquier momento para el ejemplo principal. Sin embargo, tiene sentido explicar otras técnicas similares que el lector todavía puede encontrar en la Web, en caso de que se encuentren con ellas y deban saber en que consisten.

Por ejemplo, todos los ejemplos usarán el doctype de HTML5, pero aún así, explicaremos como sería con otros doctypes porque el lector todavía los encontrará en el mundo real.

  • Doctype: Siempre utilice uno y use el de HTML5, a menos que esté mostrando deliberadamente un ejemplo antiguo.
  • El HTML y las CSS deben ser válidos, a menos que esté mostrando deliberadamente un ejemplo erróneo.
    • Comentario: Use CSS 3 cuando valide las CSS.
    • Excepción 1: Errores de validación.
    • Excepción 2: Se permiten características CSS experimentales que hacen uso de prefijos.
  • Incluir las CSS: Use siempre hojas de estilo internas o externas según sea adecuado, pero nunca use estilos incluidos directamente en el etiquetado, a menos que esté mostrando un ejemplo de prácticas erróneas.
  • Nunca use elementos o atributos de presentación visual, a menos que esté mostrando un ejemplo de prácticas erróneas.
  • Incluir JavaScript: Las secuencias de comando internas y externas son correctas y pueden usarse cuando sea adecuado.
    • Incluir controladores de eventos directamente en el etiquetado no es correcto.
  • Estilo de HTML: Aún cuando es correcto usar estilos de etiquetado más libres en los documentos HTML5, todavía usaremos el estilo de etiquetado de XHTML a menos que esté demostrando los estilos de etiquetado más libres específicamente.
    • Hacemos uso de las etiquetas de cierre explícitas y no nos basamos en el cierre implícito
    • Excepción a esa regla: No tenemos que preocuparnos por las barras diagonales de cierre en los elementos vacíos.
    • Usamos las comillas para todos los valores de atributo, aún cuando puedan ser solamente una palabra o un número.
    • Pero permitimos específicamente atributos booleanos abreviados, ya que eso hará que el código sea más legible y la posibilidad de errores es muy baja.
    • Utilice texto en minúsculas para el etiquetado HTML
  • Notación abreviada de CSS: Siempre use la notación abreviada, a excepción de las partes donde se explican la notación abreviada y la notación extendida, o cuando utilice una propiedad con notación extendida para anular una única propiedad establecida dentro de una notación abreviada
  • Siempre incluya todos los prefijos disponibles al demostrar características experimentales de CSS, la declaración sin prefijo siempre debe ser la última.
  • Finalice todas las declaraciones CSS con un punto y coma - ;
  • Considere el uso de CSS Lint además del validador de CSS.
  • Utilice un sangrado adecuado para HTML, CSS y JavaScript
    • 2 espacios para cada nivel de anidado en el HTML.
    • 4 espacios (no tabulaciones) para cada nivel de anidado en las CSS y las secuencias de comando.
  • El código JavaScript resultante de prácticas recomendadas debe pasar JSHint, con ajustes razonables, incluidas las reglas de espacio en blanco.
  • ¡AÑADIR MÁS MIENTRAS VAN SURGIENDO!

Foco en estándares abiertos

El material tendrá foco en los estándares abiertos del W3C, pero podrá errar en favor del pragmatismo. Así, por ejemplo, si existe la demanda específica, estará bien incluir material que cubra tecnologías específicas de un navegador (por ejemplo, las APIs de Opera Unite o XUL de Mozilla) o incluso tecnologías propietarias (como Flash). Sin embargo, éstos deben estar claramente identificados como específicos de un navegador y por lo tanto no serán el camino principal a seguir y deben ser almacenados en su propia sección de la plataforma de publicación final.

Neutralidad

Estos recursos tendrán contribuciones de muchas personas y compañías, incluyendo a creadores de navegadores y herramientas (como Opera, Mozilla, Google, Adobe, etc.) Sin embargo, el material debe permanecer tan neutral como sea posible: no debe incluirse nada que favorezca indebidamente a una herramienta sobre otra, a menos que haya una buena razón, y los ejemplos de código deben crearse siempre de manera que sean tan compatibles con múltiples navegadores como sea posible.

Accesibilidad

Somos un grupo con la accesibilidad en mente y todo el material de aprendizaje, así como los programas de estudio, deben ser accesibles para personas con discapacidad y cumplir con las pautas WCAG 2.0 del W3C, al menos al nivel AA. El material y los ejemplos deben proporcionar prácticas recomendadas para la accesibilidad.

Para más información sobre las directrices de accesibilidad, vea:

Aprender sobre accesibilidad:

Internacionalización

El contenido debe tener definido el lenguaje principal de una manera adecuada (ej: <html lang="es">) y debemos investigar las maneras para hacer que la plataforma de publicación final posea la capacidad de internacionalización adecuada.

Nota: Se necesita más información aquí, Chris le solicitará más información a Richard Ishida.