Guía de Uso para el Contribuyente o Redactor de contenidos

1. Corrección a nivel de redacción, expresión, gramática y ortografía. Calidad en la escritura
2. Redactar con lenguaje claro y conciso. Entradas cortas y fáciles de leer. Encajar el mensaje que se quiere decir en un pequeño conjunto de palabras (omitir palabras y contenidos innecesarios o redundantes)
3. Utilizar un estilo impersonal y objetivo. Evitar comentarios u opiniones que sean o puedan parecer subjetivas, así como el empleo de un lenguaje coloquial.
4. Elaborar contenidos que sean auto-explicativos, claros, directos y expositivos, sin llevar a interpretaciones confusas, situando adecuadamente en el contexto y no presuponiendo un conocimiento excesivo en la materia o tema que se está tratando.
5. Hay que tener un especial cuidado al utilizar un editor de texto, de tal forma que si se “copia y pega” texto del editor al cuadro de texto del portal, se tenga en cuenta que se pueden trasladar etiquetas no visibles de HTML que hagan que la presentación de los contenidos no sea correcta. En este sentido, conviene pasar los texto primeros a un editor de textos simples, como Notepad, y luego copiarlos en el portal o trabajar con el modo de edición de contenido HTML desactivado.

Directrices generales de redacción - Uso de enlaces

Se deben utilizar palabras claves significativas en el texto de los  enlaces, ya que este texto debe ofrecer a los usuarios la mayor información posible sobre lo que encontrarán al seguir el enlace.

Por tanto, para aprovechar toda su potencialidad es necesario evitar en los enlaces palabras de escaso valor o significado como "aquí" o "link", o descripciones que puedan llevar a confusión, como las que se refieren únicamente a secciones concretas del contenido enlazado o a descripciones que empleen una terminología distinta a la empleada en el contenido enlazado.

Licenciamiento

Los contenidos deben ser de elaboración propia o provenir de fuentes abiertas y con licencia que permita su uso. Esta directriz  debe aplicarse a todos los formatos de información incluida en MADEJA, tanto a texto como a imágenes o cualquier otro medio.

Consistencia y coherencia global

Antes de escribir en MADEJA hay que conocer lo que ya hay: su estructura y enfoque, la finalidad de cada subsistema y área, vista de pájaro a los contenidos existentes, etc. Durante este análisis, se deben identificar las áreas o partes de MADEJA que puedan tener relación con la temática que se va a abordar, y se debe ahondar en el conocimiento de dichas partes. Todo esto para garantizar que los nuevos contenidos que se elaboren tengan coherencia y sean consistentes con el resto, y puedan ser de esta forma ubicados y enlazados convenientemente con las partes de MADEJA que puedan estar relacionadas.

Ámbitos de MADEJA

Durante la redacción de contenidos se debe tener cuidado de cuidar la estructura de la redacción de forma que se separen los contenidos genéricos (MADEJA general aplicable a toda la Junta de Andalucía) de las particularizaciones o ámbitos locales de cada Consejería u Organismo (MADEJA Consejerías, incluyendo DGPD)

Contenidos generales vs específicos

Al redactar nuevos contenidos debe realizarse una distinción clara entre los contenidos genéricos, aplicables a cualquier desarrollo independientemente del ámbito o la tecnología empleada, y los contenidos específicos que hacen referencia a circunstancias relacionadas con un determinado ámbito, tecnología o herramienta. Idealmente, la estructuración de estos contenidos deberá realizarse mediante distintas áreas, existiendo  un área general en la que se incluya el contenido genérico y una serie de subáreas, cada una dedicada a una circunstancia, tecnología o herramienta concreta, que agrupen los contenidos relacionados.. (Ej: Un área agrupará pautas generales de desarrollo/base de datos, , en este área se incluirán subáreas dedicadas a la información relacionada con javaEE, Oracle, etc.)

Uso correcto de los tipos de contenidos

Utilizar cada tipo de contenido conforme a la finalidad con la que fue creado, sin "reutilizar" tipos de contenidos o "alterar" su orientación  (Ej: Una pauta no debe incluir información técnica relacionada con la directriz descrita, de igual forma un recurso no debe incluir directrices).

Uso de enlaces internos a RCJA

Tener cuidado con los enlaces a sistemas de información o páginas web sólo accesibles dentro de la RCJA o por VPN. Identificar si procede publicar dichos contenidos en Internet o bien si sólo van dirigidos a público interno corporativo. En el primer caso, intentar minimizar estos enlaces y, en caso de incluirlos, indicar claramente que sólo son accesibles por VPN o RCJA, para no dar impresión de "error" a los usuarios externos de Internet. En el segundo caso, marcar claramente dichos contenidos para su no-publicación en Internet, sólo en Corporativo.

Uso de enlaces externos

1. Uso de enlaces a webs externas: En la medida de lo posible se intentará utilizar el campo "enlaces externos" de los recursos para incluir enlaces (URLs) a páginas web externas (Internet). Se deberán minimizar la inclusión de enlaces externos incluidos en los campos de texto libre. Si se considera importante mencionar una URL externa, plantear la posibilidad de crear un recurso al efecto y relacionar dicho recurso en la pauta o procedimiento que corresponda.
2. Los enlaces externos deben dirigir a páginas oficiales relacionados con el contenido tratado, evitándose los enlaces a foros, blogs u otras páginas no oficiales.

Clasificación de vocabularios

Todos los contenidos susceptibles de aplicar unos "vocabularios" o taxonomías, deben ser clasificados para considerarse completos.

Relaciones entre contenidos

Todos los contenidos que permiten especificar relaciones a otros contenidos (pautas, procedimientos y recursos), deben ser convenientemente enlazados con los contenidos de MADEJA con los que puedan estar relacionados, antes de considerarse completos. Se recomienda que las relaciones definidas permitan navegar en ambos sentidos de la relación.

Glosario

Los subsistemas o áreas que incluyan una cantidad considerable de términos específicos de la materia que tratan deberían disponer de un glosario asociado, utilizando para ello la funcionalidad de glosario del portal.

Roles

Los contenidos que hagan referencia a actores con determinados roles o perfiles deben cuidar el alineamiento de la nomenclatura y definición de dichos roles con la propuesta unificada de roles de MADEJA

Mensaje principal breve y claro

El mensaje principal o corto de la pauta constituye el elemento más importante de una pauta, el titular que resume el mensaje esencial que trata de transmitir la pauta. Debe ser breve, conciso, pero a la vez completamente claro y directo, sin ambigüedades. Leyendo el mensaje corto se debe dar un mensaje claro de qué enunciado o directriz es la que hay que cumplir. Debe evitarse en la redacción de este texto corto el uso de expresiones del tipo “se recomienda, se requiere, etc.”, prefiriéndose una redacción en tiempo infinitivo.

Rol/es destinatario/s

En los subsistemas y/o áreas orientados a más de un rol, la redacción de la pauta deberá dejar de forma clara y explícita el rol o roles, de entre los valores posibles, a los que la pauta va dirigida y aplica su cumplimiento (esto adicionalmente a clasificar el contenido por taxonomía de rol)

Granularidad

Los contenidos de una pauta deben estar íntimamente relacionados entre sí. Si dentro de una misma pauta se tratan dos temas que no tienen una relación atómica, considerar la conveniencia de separar en dos pautas independientes o de crear un libro de pautas que incluya ambas directrices como pautas simples

 Desarrollo de la pauta

1. El desarrollo de la pauta contendrá lo necesario para aclarar, dar contexto o, como su propio nombre indica, desarrollar lo dicho en el mensaje corto, pero no debe añadir información adicional que no se infiera o relacione de manera directa con el mismo. Por tanto, si en el detalle de la pauta se detecta información adicional al mensaje corto que no lo desarrolla sino que añade conceptos nuevos de cierta relevancia, estudiar la conveniencia de extraer dichos contenidos como pauta/s aparte, si tienen entidad suficiente, o bien la posibilidad de ser incluidos en el mensaje corto de la pauta en cuestión.
2. En ocasiones, en el desarrollo de la pauta se mezclan aspectos vinculantes o de obligado cumplimiento y que, por tanto, tendrán verificaciones asociadas de forma directa, con aspectos con carácter de "recomendación" o sugerencia. Es recomendable delimitar claramente ambas partes, de forma que tanto a la hora de aplicar la pauta como de redactar las verificaciones quede claro qué parte es obligatoria y va a verificarse tal cual está expresada, de cuál es una sugerencia, consejo o posibilidad para la aplicación de la pauta, pero que no necesariamente debe seguirse "al pie de la letra" para cumplir la pauta. En todo caso, lo más recomendable es sustituir una pauta conteniendo varias directrices de distinto carácter por un libro de pautas en el que cada directriz venga expresada por una pauta simple, cada una con su carácter correspondiente.

Expresiones durante la redacción

En la redacción de la pauta se debe cuidar el uso de expresiones que transmitan un carácter de cumplimiento.

Ejemplos:

1. "Se deberán proporcionar mecanismos..."
2. "Para facilitar el uso del repositorio es recomendable crear..."

Salvo que se haga con una intencionalidad, la redacción debería quedar más "neutra", en general usando formas verbales en infinitivo o futuro.

Ejemplos:

1. "Capturar las excepciones en el código"
2. "El jefe de proyecto proporcionará mecanismos para..."

Verificabilidad

1. Se debe cuidar que el mensaje expresado en la pauta sea verificable. Se podrá verificar tanto lo expresado en el mensaje principal como en el desarrollo de la pauta.
2. La tarea de la redacción de una pauta debe estar relacionada de forma obligatoria con la de elaboración de las verificaciones asociadas, las cuales incluirán los pasos y mecanismos para la verificación del cumplimiento de los enunciados y conceptos expresados en la pauta.

Inclusión de contenido técnico

No se debe incluir en el contenido de una pauta información técnica relacionada con la directriz expresada ni ejemplos que muestren la aplicación de la directriz expresada en la pauta. En caso de que se considere necesaria la inclusión en MADEJA de esta información, deberá realizarse mediante uno o varios recursos relacionados con la pauta. 

Asociación con Áreas

Las pautas dependerán siempre de un área, estando además relacionados con otras pautas, recursos y/o procedimientos correspondientes, evitando la existencia de contenido huérfano.

Información de la actividad

Por cada actividad incluida en el procedimiento, debe incluirse una descripción de la actividad, tareas que la componen, roles responsables de la actividad, y los productos o herramientas implicadas en la actividad. Se recomienda que cada actividad tenga definida al menos una tarea.

Información de la tarea

En caso de que la información necesaria para el detalle de una de las tareas de una actividad sea demasiado extensa, esta podrá incluirse mediante un enlace a un Recurso del tipo Referencia en el que se incluya una descripción detallada de la tarea, los roles responsables de la tarea y los productos o herramientas asociados con la tarea.

Concordancia de información en el procedimiento

Los roles, productos y herramientas especificados en las tareas de una actividad deben concordar con los roles, productos y herramientas indicados en la definición de la actividad. Del mismo modo, los elementos del diagrama deben ser coherentes con el detalle indicado. 

Asociación con Áreas

Los procedimientos dependerán siempre de un área, estando además relacionados con pautas, recursos y/o procedimientos correspondientes, evitando la existencia de contenido huérfano. 

Motivación para la redacción de un recurso

Cada recurso que se defina debe haber sido referenciado o bien en textos introductorios a subsistemas/áreas o bien en pautas o procedimientos. Nunca deben definirse recursos “huérfanos”, aislados. Un recurso se define porque existe la necesidad de ampliar información sobre algo que ha sido mencionado en un área, pauta o procedimiento. Es decir, no se debe empezar a escribir en MADEJA redactando los "recursos", sino que el orden lógico de escritura es empezar por las pautas y procedimientos, en este orden,  e ir ampliando información encapsulándola en forma de recursos según se vaya viendo la necesidad.

Enlaces externos vs Recursos

Antes de especificar un enlace externo a Internet sobre cualquier tema que se mencione dentro de cualquier contenido, es necesario asegurarse que dicho tema no esté ya creado como recurso. Si está creado el recurso, se deberá hacer referencia al recurso, no al enlace externo. Si no está creado, se debe estudiar si interesaría crear un recurso al efecto o bien dejarlo sólo como enlace directo a una web externa.

Subsistema "propietario" del recurso

Antes de crear un recurso en un subsistema se debe estudiar si la temática del mismo corresponde a dicho subsistema, o bien si la "propiedad" del recurso, por la temática que ostenta, correspondería a otro subsistema distinto, en cuyo caso sólo se debería referenciar en el primero (Ej: recurso “Sonar” referenciado en el subsistema de Desarrollo, pero creado y mantenido por el subsistema de Verificación)

Uso correcto de los tipos de recursos

Si la materia que se quiere documentar como recurso no se ajusta a ninguno de los tipos de recursos definidos en el modelo de información, se debe comentar esta situación a los responsables de la Guia de Uso para estudiar si procede la modificación del modelo o bien si resulta posible encajarlo dentro de alguno de los tipos ya definidos.

En ningún caso se debe "forzar" el uso de alguno de los tipos existentes si la finalidad y atributos definidos para dicho tipo no se ajustan a las necesidades.

Directrices en recursos

En el contenido de un recurso no debe incluirse ninguna directriz, recomendación o consejo. Este tipo de información debe ser incluida en MADEJA en forma de pauta o libro de pautas que sea relacionado con el recurso. 

Tabla de Contenidos

Se debe indicar siempre el uso de la tabla de contenidos en aquellos recursos que vayan a tener un tamaño superior a una página, de tal forma que se facilite la navegación por su contenido.

Tecnologías

Si el recurso hace referencia a una tecnología concreta, deberá consignarse en el apartado correspondiente.

Asociación con Áreas

Los recursos dependerán siempre de un área, estando además relacionados con las pautas y/o procedimientos correspondientes, evitando la existencia de contenido huérfano.