Author guidelines
De SmartEiffelWiki, la enciclopedia libre.
Pequeña guía para los autores del gran libro de SmartEiffel.
Toda persona puede libremente participar en la preparación del gran libro de SmartEiffel a condición de cumplir las normas y los objetivos que figuran a continuación.
Objetivos del Wiki de SmartEiffel
Además de ser un lugar de investigación, intercambio y difusión de información, el objetivo principal del SmartEiffelWiki consiste en estar en condiciones de producir un verdadero libro que pueda imprimirse, si es necesario, en papel. El programa capaz de verificar y a continuación extraer el gran libro de SmartEiffel no se ha escrito todavía, pero si todos respetamos unos convenios y normas de redacción mínimos, eso debería de ser posible. Por supuesto, el gran libro de SmartEiffel estará siempre disponible en formato electrónico.
Prioritariamente lo que se refiere a Eiffel y SmartEiffel, por supuesto. No lo ocultamos, se trata de promover el lenguaje Eiffel y la programación basada en contratos con Eiffel. Se trata también de formar en Eiffel y de dar a conocer Eiffel. Todos los temas vinculados a la ingeniería del software son bienvenidos también en el gran libro de SmartEiffel: técnicas de pruebas con Eiffel, validación de programas con Eiffel, conceptos de orientación a objetos con Eiffel (etc. con Eiffel).
Si el tema que quieres abordar en el gran libro de SmartEiffel no se refiere en absoluto a Eiffel, no te soprendas si resulta rechazado. ¡Has sido avisado!
En la FAQ del gran libro de SmartEiffel se mencionan una serie de convenios que deben tenerse en cuenta. Los convenios y normas que siguen deben también ser respetados.
Exceptuando las páginas puramente interactivas, la inmensa mayoría de páginas debería encontrar su lugar en la "Table of contents". En realidad, sólo las páginas referenciadas desde la "Table of contents" forman parte de la versión impresa del gran libro de SmartEiffel.
Por supuesto, un Wiki es por naturaleza un lugar de discusión e intercambio. Algunas páginas deben pues utilizarse para estos debates e interacciones, y no forman parte del gran libro de SmartEiffel. Así pues, las páginas del SmartEiffel Wiki se clasifican según dos categorías. La categoría Book para las páginas del gran libro de SmartEiffel. La categoría Community para las páginas destinadas por ejemplo a las noticias y a los debates y/o intercambios en curso.
Al igual que con los nombres de página, es más sencillo utilizar siempre el mismo idioma, el inglés, para las etiquetas de navegación y el resto de informaciones similares. Este es un buen ejemplo de cumplimiento de esta regla. Cabe observar que el respeto a esta regla es tan importante como escribir el nombre de las páginas en inglés. Al igual que estos, las etiquetas de navegación pueden formar parte de una URL i servir para establecer la correspondencia entre diferentes traducciones.
Evitar los vínculos externos
Teniendo en cuenta que deseamos poder imprimir el libro, resulta preferible limitar en lo posible los vínculos externos. Se usarán siempre que se pueda vínculos internos.
Depende de ti que tengamos disponible una traducción a tu lengua favorita. No obstante, es deseable verificar siempre que existe un mínimo de correspondencia entre las páginas de las diferentes lenguas. Sin duda, la herramienta que se encargará de producier el documento en papel correspondiente al gran libro de SmartEiffel será capaz de advertirnos de que, por ejemplo, la numeración de las secciones en la versión francesa están en desacuerdo con la numeración en inglés. Ciertamente, la utilidad nos podrá avisar, pero llegará un día en que alguno de nosotros tendrá que realizar la corrección...manualmente. Se pide por tanto que cada uno de nosotros utilize frecuentemente los botones de cambio de idioma para garantizar un mínimo de coherencia.
Por supuesto, no es necesario en absoluto pedir autorización al autor de un texto para corregir una falta de ortografía o una errata!
En lo concerniente a los cambios en el estilo de una frase o el cariz de un texto, proponemos adoptar preferentemente un estilo relativamente neutral y suficientemente simple, sobretodo lo más claro posible, en fin, no demasiado pedante. No perdamos de vista que el propósito del gran libro de SmartEiffel es el de enseñar Eiffel, y no el de aspirar al premio Cervantes.
Finalmente, es bueno saber que siempre es posible revertir una modificación de estilo con unos cuantos clicks de ratón. La forma más sencilla de convencer al autor de un texto de la conveniencia de una modificación consiste a menudo en efectuarla directamente en el texto.
Para terminar con las consideraciones sobre el estilo, decir que un poco de humor no hace nunca daño a nadie. De ti depende en qué cantidad lo uses.
La página que contiene las referencias bibliográficas tiene que ser exactamente igual para todos los idiomas: el mismo número de entradas, etiquetas idénticas y orden de clasificación completamente igual. Aquí se encuentra el formato usado en el libro [ETL 1992] para las citas.
Índice manual y glosario
El índice manual y el glosario son desde luego dos páginas particulares, puesto que no conservan el orden cuando se cambia de lengua. Por ejemplo, el glosario está clasificado por orden alfabético según el idioma de la página. Los términos definidos no aparecen por tanto en el mismo orden en todas las lenguas.
Siendo así, las etiquetas de navegación deberán ser comunes, al igual que para el resto de páginas. Por ejemplo, debe haber tantas etiquetas de navegación dentro del glosario español como en el inglés. Como en resto de lugares, las etiquetas de navegación son siempre en inglés.
En caso que diversos autores no puedan llegar a un acuerdo sobre qué escribir, la discusión deberá continuar entre ellos y con el resto de la comunidad, a fin de lograr un consenso.
Si no se llega a un consenso, es el equipo SmartEiffel quien deberá decidir sobre qué se debe hacer.
Finalmente, si el consenso no existe ni siquiera entre el propio equipo SmartEiffel, Dominique Colnet tendrá la última palabra.
No dudes en completar o corregir estas reglas y convenciones.
Y sobre todo, gracias por adelantado por tu participación en el gran libro de SmartEiffel.
