Contenido


Creación con las Plantillas XML de developerWorks

Una guía paso a paso para autores, para la creación de artículos y tutoriales para publicación en developerWorks

Comments

Iniciación

Los editores de developerWorks esperan trabajar con usted para publicar su contenido. Cerciórese de haber presentado su idea a un editor y obtenido su aprobación para proseguir con su contenido antes de usar estas instrucciones. Si aún no lo hizo, llene el formulario Submit content para proponer su idea.

Los artículos y tutoriales se publican en developerWorks en formato HTML, pero se escriben en el formato XML (Extensible Markup Language). Antes de la publicación, se valida el origen XML de cada artículo y tutorial respecto a la marcación aceptable según lo definido en el esquema de developerWorks y luego se transforma en HTML para publicación a través de una hoja de estilo XSLT (Extensible Stylesheet Language for Transformations). Esa separación entre el contenido del artículo y los detalles de la presentación nos ayuda a usar procesos automatizados para administrar nuestro sitio de gran porte.

Los enfoques a la creación que ofrecemos no requieren habilidades especializadas. Si ya está familiarizado con XML o HTML, tendrá facilidad para usar nuestro artículo y las plantillas de tutorial. Si no está, puede conocer el XML al leer las recomendaciones de composición más adelante en estas instrucciones y navegar en la página New to XML en la zona XML de developerWorks.

Mientras prepara su artículo o tutorial para publicación, piense en hacer su contenido accesible a lectores con problemas de visión. En otras palabras, ofrezca alternativas de texto al contenido que no es texto, como las imágenes. Más adelante en este artículo, verá algunos ejemplos de requisitos de accesibilidad para el contenido Web. Para aprender más acerca de la accesibilidad del contenido Web, lea Web Content Accessibility Guidelines 2.0 para ver recomendaciones y técnicas.

¿Plantilla de artículo o plantilla de tutorial?

Si usted ya navegó en el sitio de developerWorks, sabe que los autores aportan artículos y tutoriales al mismo. Sus formatos y propósitos son diferentes. El editor de developerWorks puede ayudar a determinar el formato más adecuado para su idea de contenido.

Tutoriales

  • Los tutoriales tienen objetivos educativos — ellos enseñan. En lugar de simplemente listar pasos, los tutoriales explican por qué se realiza el paso y cuál es su relación con el objetivo general. Los tutoriales expresan claramente sus objetivos educativos y el tiempo necesario para la conclusión (por lo general, alrededor de dos horas). Después de concluir un tutorial, el lector debe ser capaz de repetir la tarea aprendida en forma independiente.
  • Los tutoriales pueden enseñar conceptos o cómo concluir las tareas. Muchos tutoriales enseñan tanto conceptos como tareas e incentivan a los lectores a intentar las tareas mientras leen. Para facilitar el seguimiento, los tutoriales frecuentemente incluyen muestras de código y recomendaciones para configurar el entorno del lector. Los tutoriales frecuentemente también insertan contenido en tareas separadas y manejables que constituyen el todo.
  • Los tutoriales tienen 20 ó 30 páginas en promedio cuando son impresos. Ya que la conclusión de la tarea puede llevar horas, muchos lectores imprimen el archivo PDF del tutorial para referencia durante la tarea o después de ella.
  • Un tutorial puede ser independiente o formar parte de una serie con varias partes.

Artículos

  • Los artículos frecuentemente enseñan, como los tutoriales, pero en forma menos evidente. Los artículos no informan expresamente sus objetivos educativos ni el tiempo necesario para conclusión.
  • Además de instruir a los lectores respecto a una tarea específica, los artículos también pueden introducir nuevos conceptos, arquitecturas o dispositivos de productos. Esos tipos de artículos tienen el objetivo de concienciar al lector y estimularlo a aprender más (¡quizás a través de un tutorial de developerWorks!). Otros tipos de artículo tienen un tono más persuasivo, en el cual el autor comparte su experiencia, perspectiva o enfoque específico. Otros tipos de artículos se profundizan en un nuevo producto o tecnología al entrevistar a un experto o revisar la literatura actual sobre el tema.
  • Los artículos tienen 10 páginas (o menos) en promedio cuando son impresos. Los lectores generalmente leen el contenido del artículo en línea.
  • Como los tutoriales, el artículo puede ser independiente o formar parte de una serie con varias partes.

Pasos básicos

Cree un artículo o tutorial al seguir estas etapas:

  1. Descargue el paquete del autor y descomprima el archivo.
  2. Cree una carpeta y una plantilla XML para su artículo o tutorial al usar un script del paquete.
  3. Edite la plantilla XML para añadir su contenido y luego valide el XML con relación al esquema y corrija los errores.
  4. Tenga una vista previa de su artículo o tutorial en un navegador para tener una idea de cómo se verá en developerWorks.

Paso 1. Descargue el paquete para autores

Descargue el archivo author-package zip y colóquelo en una ubicación adecuada (por ejemplo: C:\ en Windows o su directorio de inicio en Linux). Descomprima el archivo.

El directorio de developerWorks no tiene que ubicarse en el directorio raíz ni en la unidad C:\ de Windows. Sin embargo, las herramientas presuponen la ubicación de los archivos dentro del directorio de developerWorks y sus subdirectorios — por tanto, conserve la estructura de directorios y los nombres de archivo tal como están.

Si está usando Linux, también debe descargar un IBM Developer Kit para Java (consulte Recursos para obtener un enlace) e instalarlo, preferentemente en /opt/ibm, aunque usted pueda descargar una versión en tarball e instalarla en su espacio inicial si no tiene autoridad de raíz. Las herramientas de validación (descritas en "Using the developerWorks XML validation tools" sólo funcionan con las versiones de Java que incluyen Xalan (Java versión 5.0 incluye Xalan 2.7). Consulte ese artículo para conocer más detalles.

Tras descomprimir el archivo, usted debe ver un directorio (o carpeta) de developerWorks que contiene los siguientes subdirectorios:

  • readme— contiene un archivo readme.html. Ese archivo léame tiene un enlace a este artículo que está leyendo ahora.
  • schema— contiene los archivos de esquema. El principal archivo de esquema tiene el nombre dw-document-6.0.xsd. (6.0 es el nivel del esquema de developerWorks en el momento en que se escribió este artículo.)
  • tools— contiene dos plantillas (template-dw-article-6.0.xml y template-dw-tutorial-6.0.xml) como también algunas herramientas simples para ayudar a configurar y validar un nuevo artículo. El subdirectorio java contiene el origen de los programas Java™ , que se usan con la herramienta de validación y transformación de Linux, en el caso de que desee modificarlos o reconstruirlos.
  • Web— contiene las imágenes y JavaScript necesarios para tener una vista previa de su artículo o tutorial.
  • xsl— contiene los archivos de hoja de estilo usados para la vista previa. La hoja de estilo principal de cada sitio de developerWorks está en una subcarpeta apropiada al sitio — por ejemplo: 6.0/en_US/dw-document-html-worldwide-6.0.xsl para todo el mundo (inglés) o 6.0/ja_JP/dw-document-html-japan-6.0.xsl para Japón.

Las herramientas y archivos incluidos en el paquete para autores se destinan al uso en versiones de 32 bits ó 64 bits de Linux o Windows (incluyendo Windows 7). Si necesita ayuda para editar las plantillas en un sistema operativo que no sea Windows o Linux, contacte al editor de developerWorks.

Notas acerca del release

Antes de ir al Paso 2, vamos a ver lo que cambió en releases recientes este año.

En 21 de abril de 2011, corregimos errores de script que ocurren cuando los autores crean una nueva plantilla o transforman una plantilla en Windows. Ese release también incluye correcciones internas de mantenimiento en el esquema, las hojas de estilo y la plantilla, que no afectan a los autores.

En 18 de abril de 2011, añadimos soporte para la nueva zona IBM i.

En 10 de enero de 2011, añadimos soporte de fecha para el nuevo año civil y los años posteriores.

El archivo ZIP author-package y este artículo están en conformidad con el release 6.0. Debe preparar su artículo o tutorial con las hojas de estilo y el esquema 6.0. Si usó un release anterior del esquema y de las hojas de estilo de developerWorks, necesita descargar el archivo 6.0 author-package.zip desde la sección Descargas a continuación.

Artículos y tutoriales usan el mismo esquema principal (archivo xsd), pero la hoja de estilo principal varía:

  • Esquema principal: dw-document-6.0.xsd
  • Artículos y tutoriales usan una hoja de estilo apropiada al sitio local para el cual se está escribiendo el artículo. Por ejemplo: se usa 6.0/en_US/dw-document-html-worldwide-6.0.xsl para artículos en inglés para el sitio mundial, mientras que 6.0/ja_JP/dw-document-html-japan-6.0.xsl se usa para el sitio local japonés.

Paso 2. Cree una nueva plantilla

En este paso, configurará su propia copia de la plantilla de artículo o tutorial al usar una herramienta desde el paquete para autores. Eso creará un nuevo archivo, llamado index.xml, en un directorio separado. También configurará los conjuntos apropiados y ajustará la plantilla para que funcione adecuadamente en los diferentes entornos de sistema operativo.

Usando Microsoft Windows

En el directorio de developerWorks, haga doble pulsación en new-article.vbs para crear un artículo o en new-tutorial.vbs para crear un tutorial. Puede elegir cualquier nombre válido para la carpeta; los valores predeterminados son my-article y my-tutorial.

Figura 1. Creando y nombrando un nuevo artículo en Windows
Creando y nombrando un nuevo artículo en Windows
Creando y nombrando un nuevo artículo en Windows

Después de hacer clic en OK, debe ver una nueva carpeta en la carpeta de developerWorks. Tal vez sea necesario renovar su vista (View > Refresh) para verla. Esa nueva carpeta contiene su plantilla de artículo o tutorial (index.xml) y un script de validación y transformación (dw-transform.vbs).

Usando Linux

Use el script de shell new-article.sh o new-tutorial.sh en el directorio de developerWorks. (Si está ejecutando los desktops KDE o GNOME, puede ejecutar eso desde un gestor gráfico, como Nautilus o Konqueror; de lo contrario, ejecute el script en una ventana de terminal.) Usted verá un recuadro de diálogo donde puede insertar el nombre de su nuevo proyecto. Puede elegir cualquier nombre válido; los valores predeterminados son my-article y my-tutorial.

Figura 2. Creando y nombrando un nuevo tutorial en Linux
Creando y nombrando un nuevo tutorial en Linux
Creando y nombrando un nuevo tutorial en Linux

Tras seleccionar OK (o presionar Enter), debe ver una nueva carpeta en la carpeta de developerWorks. Esa nueva carpeta contiene la plantilla de su artículo o tutorial (index.xml) y un script de validación y transformación (dw-transform.sh).

Nota: Si está usando un entorno gráfico, necesitará el paquete adecuado de zenity, gdialog o kdialog para su entorno GNOME o KDE. Si está usando un entorno que no es gráfico, necesita el paquete de diálogo.

Paso 3. Edite y valide el XML

Puede elegir cualquiera de los dos métodos básicos para editar y validar su origen XML.

Usando un editor XML de validación

El uso de un editor XML de validación para editar y validar su XML ayuda a identificar errores durante el proceso. Actualmente, hay varios editores XML comerciales para Windows y Linux en el mercado. Son tres ejemplos: Rational® Web Developer para Software WebSphere® , <oXygen/> y Altova XMLSpy (consulte Recursos para ver los enlaces para descargas y documentación). Todos los tres proporcionan versiones descargables gratis para evaluación. Recomendamos que lea las instrucciones que vienen con esos productos para aprender a usarlos. Todos los archivos necesarios y de soporte que usted necesita para usar esos productos — u otros editores XML comerciales — para desarrollar su artículo o tutorial están en el archivo author-package.zip de developerWorks.

También hay algunos editores XML gratis disponibles. Además de la versión comercial de XMLSpy mencionada arriba, Altova introdujo una Home Edition gratis de XMLSpy. XML Copy Editor es un editor gratis liberado bajo la licencia GNU General Public License. Además, hay plug-ins disponibles para la plataforma Eclipse que usted puede usar para preparar documentos XML. Consulte Recursos para obtener los enlaces.

Al usar un editor XML de validación o un entorno de trabajo, tenga en mente:

  • En las plantillas que creó con los scripts arriba, las referencias al esquema y a los archivos de hoja de estilo son relativas a su directorio de tutorial o artículo. Tal vez sea necesario cambiar esas referencias a referencias absolutas. Por ejemplo: tal vez sea necesario cambiar ..\schema\6.0\dw-document-6.0.xsd a algo como C:\developerworks\schema\6.0\dw-document-6.0.xsd. Quizás sea necesario realizar un cambio semejante en la hoja de estilo. Usted necesitará cambiar el nombre y la ubicación de la hoja de estilo si desea preparar un artículo para un sitio local, como el de Japón. En algunos editores, tal vez sea necesario especificar la ubicación de esos archivos a través de otros medios de configuración.
  • Si transforma su tutorial o artículo en un editor XML y ninguna de las imágenes es exhibida, es probable que el editor haya creado el archivo HTML en un directorio usado para almacenamiento temporal. En ese caso, usted necesitará salvar el archivo HTML generado en su directorio de artículos (my-article, en nuestro ejemplo) y abrirlo en la GUI del editor XML o con un navegador.

Usando un editor de texto y herramientas de validación

Si no encuentra un editor XML de validación que le agrada o prefiere no tomarse un tiempo ahora para aprender a usar uno, puede usar su editor de texto preferido para editar la plantilla XML y luego usar las herramientas suministradas en el paquete para autores (dw-transform.vbs para Windows o dw-transform.sh para Linux) para validar el XML y transformarlo en HTML. Luego, puede tener una vista previa del HTML en un navegador. Consulte el artículo complementario "Using the developerWorks XML validation tools" para ver detalles acerca del uso de esas herramientas sencillas.

Paso 4. Tenga una vista previa de su artículo o tutorial

Puede tener una vista previa de su artículo o tutorial para obtener una idea general de cómo se verá la salida final. Sin embargo, habrá algunas diferencias entre la versión de la vista previa y la versión final. Cuando tenga una vista previa de su tutorial o artículo, enfoque el contenido y no se preocupe por las cuestiones de presentación o estilo. Realizaremos las modificaciones necesarias al realizar la edición final.

Si está usando un editor XML de validación, verifique la documentación para ver instrucciones de cómo transformar el XML en un archivo HTML y luego ver ese archivo en un navegador. Algunos editores tienen una opción de vista previa en el navegador para simplificar ese paso.

Si está usando un editor de texto y los scripts de developerWorks, se creará el HTML de salida en su carpeta de artículo o tutorial. Abra index.html con un navegador. Hay instrucciones más detalladas sobre el uso de esos scripts en "Using the developerWorks XML validation tools".

Recomendaciones de composición

Los archivos XML que usted genera en el Paso 2 son la mejor fuente de recomendaciones de gran amplitud acerca del desarrollo de su artículo o tutorial. Los comentarios extensos en las plantillas guían a usted en todos los aspectos de codificación de su artículo o tutorial. He aquí algunas recomendaciones que pueden ser útiles:

  • ¿Está componiendo en Microsoft Word u OpenOffice Writer?

    Puede usar la plantilla de Word o Writer, en lugar de la plantilla XML; usted encuentra detalles completos en "Authoring with the developerWorks Word and Writer templates."

    Como alternativa, puede cortar y pegar desde otros formatos de archivo en la plantilla XML.

    • Si corta y pega desde un archivo con formateo integrado, como un archivo de Word o Writer, use las posibilidades de su editor para pegar (o pegar especial) como texto o salve el archivo como TXT antes de cortar y pegar desde él. No corte y pegue directamente desde un archivo formateado.
    • Si su documento de Word o Writer tiene imágenes integradas, no se preocupe por extraerlas; simplemente reenvíe el documento de Word o Writer al editor de developerWorks y nuestro equipo de diseñadores visuales extraerá y refinará las imágenes.
    • Si su documento de Word o Writer tiene "Track Changes" activado, cerciórese de desactivarlo antes de cortar y pegar en la plantilla XML; de lo contrario, ¡todo el material suprimido reaparecerá mezclado a su texto!
  • Etiquetas de cierre. Cerciórese de usar etiquetas de cierre. Por ejemplo: toda etiqueta de párrafo (<p>) necesita su etiqueta de cierre (</p>). Además, elementos vacíos — como la etiqueta de quiebra (<br />) y la etiqueta de imagen (<img />) — necesita una barra invertida de cierre (/).
  • Etiquetas a evitar. No use etiquetas de span, etiquetas de fuente de código, clases de fuente o etiquetas CDATA.
  • Listados de código. Al incluir listados de muestra de código en línea en su artículo o tutorial:
    • La longitud máxima de la línea de código es 90 caracteres, INCLUYENDO espacios en blanco. La plantilla tiene una muestra con una línea de regla para ayudar.
    • La longitud máxima del listado de código es 100 líneas, INCLUYENDO líneas en blanco.

      Si su listado de código tiene más de 100 líneas, segméntelo en listados individuales o saque extractos de las líneas más importantes y considere la posibilidad de ofrecer todo el listado de código como muestra de código descargable en la sección "Descargas" de su artículo o tutorial.

    • Evite insertar directamente en el código de origen los datos referentes a espacios en blanco o tabulaciones al final de las líneas del código de muestra, pues están incluidos en los 90 caracteres por línea.
    • Evite usar tabulaciones en el inicio de una línea de código de muestra. Si necesita sangrar, use espacios en blanco.
    • No use etiquetas CDATA. Si necesita exhibir etiquetas XML — como paréntesis angulares — en su muestra de código, use < y > (vea otros caracteres especiales en Tabla 1).
    • No use color. Si desea resaltar una parte de su muestra de código, use énfasis fuerte (<strong> y </strong>) en lugar del color.
  • Muestra de código descargable Al proporcionar muestra de código descargable para la sección "Descargas" de su artículo o tutorial, comprima el código y envíe el archivo ZIP a su editor por separado.
  • Ilustración. Cree todos los archivos de ilustración, incluyendo las capturas de pantalla, como archivos JPG o GIF y cerciórese de que no excedan 580 píxeles de ancho. Envíe los archivos de ilustración al editor. Consulte "Illustrating your article or tutorial for developerWorks" para conocer más acerca de cómo crear y entregar gráficos efectivos.
  • Líneas de comentario. Para ver mejor su contenido a medida que lo desarrolla, puede eliminar las líneas de comentario del archivo del artículo a medida que se familiariza con el etiquetado.
  • Accesibilidad. Tenga en cuenta a los lectores con problemas de visión y cerciórese de que su artículo o tutorial cumpla con los requisitos de accesibilidad para el contenido Web. Específicamente: (1) use color con moderación o no lo use e (2) incluya alternativas de texto al contenido que no sea texto. Típicamente, el segundo requisito se aplica a las imágenes de su artículo o tutorial. Añada contenido antes o después de las imágenes para explicarlas bien a personas que no la pueden ver. Además, proporcione una breve descripción de la imagen en el atributo "alt" de la etiqueta <img>. No cree imágenes a partir de tablas ni use demasiado texto contenido en una imagen. Ejemplos de esos requisitos de accesibilidad son abordados más detalladamente en Illustrating your article or tutorial for developerWorks."
  • Caracteres especiales. Codifique los caracteres especiales como se muestra en Tabla 1:
Tabla 1. Caracteres especiales
CaracterCodificación XML
caracter & (&)&amp; (Siempre codifique caracter & como &amp; — incluso en URLs.)
Apóstrofo (')&apos;
Paréntesis angular izquierdo o símbolo de menor-que (<)&lt;
m-dash (—)<mdash />
Comilla (")&quot; (En texto, use la comilla del teclado pero para incluir una comilla en un elemento XML use &quot;)
Marca registrada (®)<reg/> (Los autores pueden insertar símbolos de marca registrada, pero no están obligados a hacer eso; el equipo editorial de developerWorks se encargará de las marcas registradas.)
Paréntesis angular derecho o símbolo de mayor-que (>)&gt;
Marca registrada (™)<trade/> (Los autores pueden insertar símbolos de marca registrada, pero no están obligados a hacer eso; el equipo editorial de developerWorks se encargará de las marcas registradas.)

Por ejemplo: para incluir paréntesis angulares en una sección del código:

<TABLE border="0" width="100%">

Usted codificaría lo siguiente en la plantilla XML:

&lt;TABLE border="0" width="100%"&gt;

Convenciones de resalte

¿No está seguro acerca de cómo resaltar cadenas de caracteres de código? ¿Se enfatiza un título de artículo o libro? ¿Cuándo no se debe usar ningún resalte? Tabla 2 muestra las convenciones de resalte recomendadas para artículos y tutoriales de developerWorks.

Tabla 2. Resalte recomendado
Elemento resaltadoResalte recomendadoEjemplo de codificación XML
"Título de artículo"Comillas"Introduction to Android development"
Título de libroÉnfasis<em>AI Application Programming</em>
ClaseCódigo en línea<code type="inline">Command</code> class
Listado de códigoSección de código<code type="section">
struct my_data_structure {
    int value;
    struct list_head list;
};
</code>
Cadena de caracteres de código en una fraseCódigo en línea<code type="inline">my_hrtimer_callback</code>
Nombre de columna o serieÉnfasisLa serie <em>Learn Linux 101</em> en developerWorks
Nombre de comandoCódigo en línea<code type="inline">Print</code> command
Nombre de diálogo o panelSin resalteEl diálogo Installation options
ÉnfasisÉnfasis fuerte. Por ejemplo: "La longitud máxima de la línea de código es 90 caracteres."La longitud máxima de la línea de código es <strong>90 caracteres</strong>.
Nombre de archivoSin resaltesample.zip
Control de GUIÉnfasis fuerte. Por ejemplo: "Haga clic en Options > Preferencias."Haga clic en <strong>Options</strong> > <strong>Preferences</strong>.
Elemento HTMLCódigo en línea<code type="inline">title</code> element
Palabra claveCódigo en línea<code type="inline">cloud</code> keyword
MacroCódigo en línea<code type="inline">LIST_HEAD</code> macro
Título de revistaÉnfasis<em>Linux Magazine</em>
Texto de mensaje o prompt dirigido al usuarioCódigo en línea<code type="inline">The queue was created successfully</code>
MétodoCódigo en línea<code type="inline">execute()</code> method
ObjetoCódigo en línea<code type="inline">Zend_Service_Amazon_Sqs</code> object
Nombre de vía de accesoSin resalteC:\jdk1.6.0_18
Término definido en el contextoÉnfasis<em>timer wheel</em>
"Título de tutorial"Comillas"Create modern Web sites using HTML5 and CSS3"
Tipo (como int o long)Código en línea<code type="inline">int</code> type
URL en el textoSin resaltewww.ibm.com/developerworks/
VariableÉnfasis<em>your-file</em>
Nombre de sitio WebSin resalteEl sitio Web de developerWorks
Elemento XMLCódigo en línea<code type="inline">heading</code> element

Enviando su artículo o tutorial a developerWorks

Tras finalizar su obra maestra, usted está listo para enviarla al editor de developerWorks. Envíe por e-mail el archivo XML de su artículo o tutorial (junto con la muestra de código o los gráficos asociados) al editor. Para ver guías detalladas y recomendaciones de cómo crear y enviar los gráficos de su artículo, consulte Ilustrando su Artículo o Tutorial para developerWorks."

Si tiene dudas o problemas, contacte a su editor para obtener ayuda adicional.


Recursos para Descargar


Temas relacionados


Comentarios

Inicie Sesión o Regístrese para agregar comentarios.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=90
Zone=WebSphere
ArticleID=678657
ArticleTitle=Creación con las Plantillas XML de developerWorks
publish-date=06072011