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)
3. Utilizar un estilo impersonal y objetivo. Evitar comentarios u opiniones que sean o puedan parecer subjetivas.
4. Elaborar contenidos que sean autoexplicativos, 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.
   

Directrices generales de redacción - Uso de enlaces

Se deben utilizar palabras claves en los enlaces, ya que éstos deben ofrecer a los usuarios la mayor información posible sobre lo que se 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".

Licenciamiento

Los contenidos deben ser de elaboración propia o las fuentes deben ser abiertas y con licencia que permita su uso (aplica a todos los formatos, tanto texto como 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 SGISI)

Contenidos generales vs específicos

Debe prestarse atención a realizar una distinción clara y explícita entre contenidos genéricos frente a contenidos específicos que se circunscriben a un ámbito en concreto (tecnología, metodología...). Idealmente estos bloques irán agrupados en distintas áreas, para mejor localización. Ej: pautas generales de desarrollo/base de datos, frente pautas específicas de javaEE, Oracle, etc.

Uso correcto de los tipos de contenidos

Utilizar cada tipo de contenido conforme a la finalidad con la que fue creado (no "reutilizar" tipos de contenidos y "alterar" su orientación).

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 es accesible 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 indicar URLs a páginas web externas (Internet). Se deberán minimizar los enlaces externos introducidos en cualquier parte de 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. Estrategia para enlaces a páginas externas de Internet no reconocidas oficialmente.

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.

Glosario

Los subsistemas o áreas que incluyan muchos 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. 

 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. 

 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. 

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. Con la redacción de una pauta debe venir obligatoriamente la tarea 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.

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.