Diferencia entre revisiones de «Documentación en Software libre»

De wiki EOI de documentación docente
Saltar a: navegación, buscar
 
Línea 135: Línea 135:
 
|Pie vídeo 4=
 
|Pie vídeo 4=
 
}}
 
}}
|Estado=esbozo
+
|Estado=completo
 
}}
 
}}
 
{{Prueba
 
{{Prueba
 
|Prueba=No
 
|Prueba=No
 
}}
 
}}

Revisión actual del 11:23 24 may 2012


Estado de desarrollo de la sección: completo completo

Wikilibro: Software libre > Capítulo 7: Entornos y tecnologías de desarrollo

Sección 6

Documentación
En el mundo del software libre, apenas se usan procesadores de texto WYSIWYG y otras herramientas ofimáticas que tanto éxito tienen en otros entornos, a pesar de haber ya herramientas libres, como OpenOffice. Ello es debido a varios factores importantes:
  • Es conveniente mantener la documentación bajo control de fuentes, y los sistemas de control de fuentes, como CVS, aunque admiten formatos binarios, prefieren formatos textuales transparentes, editables con un editor de texto normal y procesables con herramientas desarrolladas para programas, que nos permitan ver fácilmente las diferencias entre versiones, generar y aplicar parches basados en esas diferencias, y realizar operaciones de mezcla.
Nota: En Unix las herramientas que hacen estas operaciones más comunes son diff, diff3, patch y merge.
  • Ciertas licencias de documentación libre, especialmente la GFDL (“Licencia de documentación libre de GNU”), exigen formatos transparentes, sobretodo por facilitar el trabajo a los que realicen documentos derivados.
  • Las herramientas WYSIWYG (what you see is what you get) generalmente no contienen más información que la estricta de visualización, haciendo muy difícil, si no imposible, el procesamiento automático, como identificar autores o título, y la conversión a otros formatos. Incluso aunque permitan conversión de formatos, ésta suele hacerse de forma interactiva, siendo muchas veces imposible automatizarla (con make, por ejemplo).
  • Generalmente las herramientas ofimáticas generan unos formatos de ficheros muy voluminosos, asunto muy desagradable para los desarrolladores o los repositorios.

Por todo ello el programador libre, acostumbrado también a programar y compilar, prefiere formatos de documentación transparentes, en muchos casos simple texto puro, en muchos otros formatos de documentación procesables.

Los formatos procesables utilizados no son muchos. Tradicionalmente en el mundo Unix los programas se han documentado en los formatos esperados por la familia de procesadores roff, con versión libre[groff] de Norman Walsh. No obstante esta práctica se ha ido abandonando, excepto para las páginas de manual tradicionales, ya que es casi obligado preparar páginas de manual para las herramientas más básicas del sistema. Debido a que muchas páginas de manual han crecido excesivamente, de modo que difícilmente se les puede llamar páginas, fue necesario elaborar un formato alternativo hiper-textual, que permitiera seguir documentos estructurados con índices y referencias cruzadas. El proyecto GNU diseñó el formato texinfo[texinfo] y lo convirtió en su estándar. Este formato permite obtener documentos navegables con la herramienta info o dentro del editor emacs, y a su vez obtener documentos impresos de calidad con ayuda del procesador de textos TeX, de Donald Knuth[knuth:tex].

El formato texinfo puede traducirse a HTML multipágina si se desea, y mucha gente prefiere ver la información con un navegador Web, pero se pierde la capacidad de búsqueda de palabras en un documento. Esta es una de las consecuencias indeseables de la popularidad de HTML, ya que los navegadores no implementan el concepto de documento multipágina, a pesar de que existen elementos link que permiten enlazar las partes.

Existe una imperiosa demanda de que los documentos complejos se puedan ver como páginas Web multipágina fácilmente navegables. Hay gente que escribe documentación en LaTeX[lamport:latex], también aplicación de TeX, muy popular entre los científicos, más expresivo que Texinfo, y convertible a HTML multipágina con ciertas herramientas[goosens:texweb], siempre que se guarde cierta disciplina. En efecto, las aplicaciones de TeX son conjuntos de macros que combinan operadores tipográficos de muy bajo nivel para convertirlos en lenguajes abstractos que trabajan con conceptos de alto nivel (autor, título, resumen, capítulo, apartado, etc.). Si sólo se utilizan las macros básicas, la conversión es sencilla. Pero como nadie impide usar operadores de bajo nivel y, además, existen cantidades enormes de paquetes de macros fuera de la capacidad de mantenimiento de los mantenedores de los conversores, es difícil conseguir que las conversiones salgan bien.

Contenido

Docbook

El problema radica en que no existe separación entre contenido y presentación, ni en las aplicaciones de TeX ni en las de nroff, ya que la abstracción se construye por capas. Esta separación la tienen las aplicaciones de SGML[sgml] y XML[xml], donde la presentación se especifica con hojas de estilo completamente separadas. Muy pronto empezaron a utilizarse aplicaciones muy sencillas de SGML, como linuxdoc y debiandoc, pero debido a su escasa capacidad expresiva, se optó por ir a DocBook[walsh:docbook].

DocBook es una aplicación de SGML originalmente desarrollada para documentación técnica informática, y hoy con una variante XML. DocBook es hoy el estándar de formato de documentación libre para muchos proyectos (Linux Documentation Project, KDE, GNOME, Mandriva Linux, etc.) y un objetivo a alcanzar en otros (Linux, *BSD, Debian, etc).

Sin embargo DocBook es un lenguaje complejo, plagado de etiquetas, por lo que es conveniente disponer de herramientas de ayuda a la edición, aún escasas y elementales, siendo la más popular el modo psgml de emacs. También es pesado de procesar y los procesadores libres aún generan una calidad de documentos poco atractiva.


Wikis

Mucha gente encuentra demasiado complicado escribir documentación con lenguajes tan complejos como DocBook y mecanismos de colaboración como CVS. Por ello se ha hecho muy popular un nuevo mecanismo de colaboración para la elaboración de documentos en línea vía web llamado Wiki, inventado por Ward Cunningham[ward:wiki], puesto por primera vez en servicio en 1995, y hoy ampliamente utilizado en muy diversas variantes para elaborar documentos muy dinámicos, no destinados a ser impresos, y muchas veces con una vida corta (por ejemplo, organización de una conferencia).

Al contrario que DocBook, un Wiki tiene un lenguaje de marcas muy simple y conciso, que recuerda la presentación final, sin ser exactamente como ella. Por ejemplo, los párrafos se separan por una línea en blanco, los elementos de listas empiezan por un guión si no se numeran y por un cero si se numeran, o las celdas de tablas se separan por barras verticales y horizontales.

Tampoco existe el concepto de documento completo, sino que un Wiki es más bien un conjunto de pequeños documentos enlazados que se van creando a medida que es necesario explicar un nuevo concepto o tema. La creación de los documentos es casi automática, ya que la herramienta de edición muestra muy claramente que hemos introducido un concepto (a través de un NombreWiki, casi siempre dos palabras juntas con la primera letra en mayúsculas). Casi ningún Wiki admite hiperenlaces dentro de la misma página.

Al contrario que en CVS, cualquiera puede escribir en un Wiki, aunque se aconseja que se identifique el autor con un registro previo. Cuando se visita un Wiki veremos que todas las páginas tienen un botón para permitir su edición. Si se pulsa, el navegador nos mostrará en un formulario el fuente del documento, que podremos cambiar. No es una edición WYSIWYG, lo que disuade al que quiera fastidiar, pero es tan sencillo que cualquier interesado puede modificar documentos con muy pequeño esfuerzo.

Los Wikis llevan su propio control de versiones de documentos, de modo que generalmente están accesibles todas sus versiones con indicación de quien las hizo y cuando. También se pueden comparar con facilidad. También suelen llevar mecanismos de búsqueda, al menos por nombre de página y por palabra contenida.

Normalmente el autor original de una página querrá enterarse de las modificaciones que se le hacen. Para ello puede suscribirse a los cambios, recibiendo notificaciones de los mismos por correo electrónico. A veces el que ve un documento no se atreve a cambiar nada, pero puede hacer un comentario. Normalmente toda página wiki tiene asociado un foro de comentarios que se pegan al final del documento y que, bien el autor original, bien alguien que asuma el rol de editor, puede emplearlos para reformar el texto original, posiblemente moviendo frases de los comentarios a los sitios oportunos.

Sugerencia: La mejor forma de entender un Wiki es accediendo a uno y experimentando en una página destinada a ello, denominada habitualmente SandBox.


< Sección anterior
Gestión de fuentes

Sección siguiente >
Gestión de errores y otros temas