¿Cómo documenta su trabajo, procesos y entorno?

¿Estás usando un formato wiki? Si es así, ¿qué producto? (MediaWiki, Confluence, Sharepoint, etc.)

¿Has creado una base de conocimiento? (Documentos cortos orientados a problemas / soluciones).

¿Qué desafíos encuentra al crear documentación que funcione, para que no reciba la llamada cuando está de vacaciones?

Para mí, encuentro que a menudo hay una cierta cantidad de "inercia" organizacional involucrada con la obtención de la documentación. Parece ser un tipo diferente de persona que puede hacer una tarea, luego pensar en cómo la hizo y describirla para que otra persona pueda hacerlo: un tipo de fuerzas para que "te meta" y no todos se sientan cómodos haciendo eso.

Actualizar

Las respuestas hasta ahora incluyen

• Confluencia
• Flexwiki
• Fogbugz
• Mediawiki (con complementos como fckeditor)
• Sharepoint
• TWiki
• Documentos de Word / Excel / Visio
• Guiones documentados

Editar: ¿No está documentando implícitamente su red con su sistema de monitoreo? Nagios siempre ha alentado el uso de la directiva de los padres para reflejar la estructura de su red, y la directiva notes_url está diseñada para permitirle enlazar a una wiki u otra documentación basada en el navegador. Entonces, aquí la "documentación" se divide entre el "documento vivo" del sistema de monitoreo y la documentación fuera de línea más detallada en una wiki. Como paso mucho tiempo mirando a Nagios, tiene sentido esforzarse para que sea lo más informativo posible.

Comentando sobre las herramientas.

Hemos probado las wiki en línea, pero encontramos una serie de limitaciones, que pueden ser gustos personales, pero que incluyen la estructura del documento y, lo más crítico, tener que estar conectado al servidor de documentación.

Estar conectado es un problema grave si está fuera de línea o en el sitio (obviamente, puede mitigar el sitio con una conexión SSL segura, etc.)

Nuestro proceso de documentación actual es:

• generador de html estático
• sintaxis de rebaja
• sistema de versionado distribuido

Tenemos un diseño 'formal' para la documentación y que proporciona la estructura de los menús (y el CSS asociado para el estilo visual, etc.)

Generador HTML estático

Utilizamos un generador html estático interno basado en cubictemp y una serie de otras herramientas: pigmentos , docutils .

Las páginas generadas son (¿no?) Obviamente feas, ya que la mayoría de nosotros / nuestros administradores de sistemas / programadores sabemos lo que es estéticamente bello pero tenemos una falta total de coordinación para construirlo.

Pero permite / incluyamos archivos de configuración, scripts de muestra, pdf, etc., sin tener que preocuparnos de que el formato html lo arruine o se preocupe por dónde encontrarlo en el 'servidor' para descargarlo.

Si no es HTML, simplemente suéltelo en la carpeta y agréguele un enlace de URL.

HTML proporciona una estructura 'potencial' para el diseño, y también proporciona de manera crítica 'vinculación' entre elementos de conocimiento / contenido (así como mecanismos de estructura base, como la posibilidad de crear menús, tablas de contenido, etc.) Con HTML, cada usuario ahora puede ejecutar un pequeño servidor web en su máquina, ya sea lighttpd o algo pequeño, o simplemente explotar con Apache o IIS.

Todas nuestras máquinas tienen la fuerza para servir html básico y funcionan lo suficientemente bien para nosotros.

Sintaxis de MARKDOWN.

Utilizamos una versión bastarda de MARKDOWN, Textish o reStructuredTEXT para permitir que nuestros jugos 'creativos' escriban documentación sin tener que preocuparse por HTML.

También significa que todos pueden usar su editor favorito (yo uso Scintilla en Windows y * Nix) mientras que los demás aquí usan vi / vim.

Sistema de versiones distribuidas.

Usamos Git para 'distribuir' la documentación entre los usuarios. Ah, y también usamos su capacidad de versiones.

La ventaja clave para nosotros es que todos podemos trabajar en la actualización de la documentación sin tener que estar conectado al servidor, y sin tener que publicar trabajos "completos". Todos podemos trabajar en las mismas partes de la documentación, o en diferentes partes, o simplemente consumir la información.

Personalmente, odio estar atado a un servidor para actualizar blogs y mucho menos wiki. Git funciona bien para nosotros.

Comentando sobre el flujo de trabajo

Las Wiki parecen ser la "moda" para la difusión / codificación del conocimiento, pero como se comentó en otros lugares, todos los procesos se vuelven difíciles de mantener, y encontrar la combinación de herramientas que mejor respalde las necesidades de sus equipos y sea sostenible llevará tiempo.

Las mejores soluciones acaban siendo descubiertas y no obligatorias.

Hemos comenzado a usar DokuWiki donde trabajo.

Desde el sitio web de Dokuwiki:

DokuWiki es un Wiki que cumple con los estándares y es fácil de usar, principalmente dirigido a crear documentación de cualquier tipo. Está dirigido a equipos de desarrolladores, grupos de trabajo y pequeñas empresas. Tiene una sintaxis simple pero poderosa que asegura que los archivos de datos permanezcan legibles fuera del Wiki y facilita la creación de textos estructurados. Todos los datos se almacenan en archivos de texto sin formato; no se requiere una base de datos.

Encontré que Dokuwiki es el más fácil de implementar porque no requiere base de datos y fue fácil de configurar. También hubo módulos complementarios que permitieron usar mis inicios de sesión de cuenta de Active Directory existentes en lugar de tener que crear cuentas para todos, lo que fue una gran ventaja sobre la mayoría de los otros sistemas wiki que encontré. También tiene el control de versiones típico, donde puede ver quién publicó qué y dónde, y tiene la capacidad de retroceder a una versión anterior fácilmente si es necesario. También incluyen una página de inicio personalizable que permite cambiar fácilmente el tipo de contenido que mejor se adapte a su entorno.

Doku Wiki o Sharepoint para otras cosas que encajan en un gráfico.

Te acostumbras bastante rápido a publicar en un wiki y la sintaxis no es realmente compleja. Es muy fácil organizar la información y hacer que sea más fácil encontrarla más tarde por otra persona.

Utilizo visio para hacer gráficos para explicaciones más claras (exportar como JPEG).

Estamos usando una wiki. De hecho, estamos usando MediaWiki. Además de MediaWiki, tenemos instalada la extensión Semantic Mediawiki , que en realidad convierte nuestra MediaWiki en una especie de base de datos de tipo suelto que podemos consultar con Categoría, título, contenido, etc.

Por ejemplo, supongamos que quiero ver todos los nombres de red que se enrutan a través del Clúster F. Todo lo que necesito hacer es usar la página Especial: Preguntar para consultar [[Categoría: cname]] [[destino :: cluster_f]] .. . y devolverá todas las páginas que están categorizadas como cname con el destino como cluster_f.

Apoyamos a unos cientos de clientes muy dispares, por lo que tener esa documentación en un lugar central (y tenerla entrecruzada para que los casos especiales permanezcan documentados y vinculados al conjunto) es algo muy útil. Obviamente, nuestra documentación debe mantenerse, pero puede adoptar un enfoque más "jardinero" para el mantenimiento porque el kit de herramientas de mediawiki para mantener actualizado un gran conjunto de datos ya es bastante maduro.

Con los complementos correctos, Trac puede convertirse en una combinación de ticket y sistema wiki. Esto facilita que sus entradas se vinculen a artículos wiki y viceversa.

Un par de complementos que me gustan:

• Complemento de entradas privadas . Trac está construido como una base de errores donde todos los tickets y sus respuestas son públicos. Eso no es apropiado para un sistema de tickets de TI, pero este complemento lo soluciona.
• Complemento Trac WYSIWYG . Seamos realistas, la mayoría de la gente no va a aprender wikisyntax para hacerte feliz. Esto les da un editor 'lo que ves es lo que obtienes' tanto para tickets como para páginas wiki.

Hay bastantes personalizaciones más para Trac. ¡No es difícil configurar y personalizar un sistema Trac a su gusto!

En mi trabajo anterior usé Twiki. Funcionó bastante bien.

Además de eso, tiendo a automatizar la mayoría de las tareas y documentar las secuencias de comandos (no siempre con mucho entusiasmo, pero aún así ...). La documentación de los scripts se realiza fácilmente en el proceso de diseño, por lo que no hay gastos generales reales ...

La combinación de ambos (y el uso del control de versiones para los scripts) funcionó bastante bien.

Una mezcla de JIRA, Confluence y Word Documents.

Institucionalizando el conocimiento

Comenzamos con documentos. Luego almacenamos algunos de ellos en las bibliotecas de Sharepoint. Luego, recientemente nos mudamos a la wiki de Sharepoint. Me gusta el enfoque de baja fricción de la wiki para actualizar cosas rápidamente, aunque las wikis de Sharepoint dejan algunas cosas que desear en soporte de gráficos y soporte de formato para cosas como tablas. Está bien para el texto y el editor incorporado permite un formato HTML básico y listas ordenadas / no ordenadas. Existen otras alternativas de bajo costo a Sharepoint.

También tenemos una especie de base de conocimiento informal para nuestros tickets de soporte en nuestro software de mesa de ayuda, Numara's Track-It. No es perfecto pero funciona.

Conseguir que el personal utilice el conocimiento institucionalizado

Estoy de acuerdo con su evaluación de que obtener conocimiento institucionalizado es solo una parte de la batalla. Si su organización y las personas no están acostumbradas a "investigar primero, pregunte después", encontrará que prevalece la vieja forma: todos seguirán buscando respuestas a los gurús formales e informales, y para algunas personas siempre será más fácil preguntar la persona a tu lado que buscar por tu cuenta.

Lidiar con esto implicará cierta gestión del cambio; Como la mayoría de las iniciativas de cambio exitosas que afectan a algo más que un pequeño equipo, será útil contar con el respaldo y el apoyo de la gerencia. Realmente tienes que forjar un nuevo comportamiento en dos direcciones; alguien necesita capturar el conocimiento y la gente necesita usarlo. Aún más difícil es que las personas también necesitan mantener esos datos actualizados.

Solo algunas ideas: probablemente será necesario alentarlo en forma de una política formal que establezca que los tickets y problemas resueltos deben documentarse en la base de conocimiento o wiki antes de que puedan considerarse cerrados. Además, los líderes de conocimiento a los que normalmente se les hacen preguntas no siempre deben ofrecer respuestas a pedido; necesitan señalar a las personas a los wikis y acostumbrarlos a comprobar allí primero. Otra cosa sería poner los datos a disposición de los usuarios para autoayuda, de modo que el problema podría resolverse antes de que se convierta en otro elemento que el personal técnico tiene que hacer malabarismos.

Lo que sería bueno es que nuestro sistema de mesa de ayuda tenga un sistema similar a StackOverflow y ServerFault: al escribir una pregunta, el motor de búsqueda encuentra elementos similares y los ofrece, para que los usuarios puedan verlos incluso antes de enviar la pregunta.

En mis dos últimos lugares de trabajo, utilicé Sharepoint's Wiki, junto con una biblioteca de documentos que contenía ciertos documentos (como DRP y planes de actualización únicos) que no se pueden crear fácilmente como documentos Wiki. Esos documentos tenían enlaces desde el Wiki. Wiki tiene muchas ventajas en esta área, ya que muchas personas pueden editarlo, el control de versiones está integrado, es fácil de buscar y accesible, etc. Para escribir rápidamente notas o ideas, usaría OneNote o una pizarra.

Ya había creado algunas bases de conocimiento antes, en formato de foro (tanto en Lotus Notes como en MS Sharepoint), pero debo decir que rara vez la gente las está revisando para ver si ya se resolvió un problema determinado. Tal solución debe venir desde el primer día con un motor de búsqueda muy fuerte y efectivo.

Si desea crear documentos que puedan usarse mientras está de vacaciones, escríbalos como si estuviera tratando de instruir a uno de sus padres. Esto no es 100% infalible, pero a veces ayuda. Depende de quién lo lea.

Sharepoint es agradable.

Sus funciones de búsqueda tienen la capacidad de indexar casi cualquier tipo de documento, lo que facilita la búsqueda de documentación.

También puede crear algunas plantillas, lo que puede facilitar las cosas si, por ejemplo, tiene una hoja de información estándar para cada servidor que construye.

También puede versionar sus documentos para que tenga un historial de auditoría de cambios en la documentación.

Además, se puede acceder a los archivos contenidos en las bibliotecas de documentos a través de la web, en perspectiva o a través de un recurso compartido unc de inmediato.

Hemos utilizado MediaWiki (con fckeditor) durante varios años, aunque debo decir que sería bueno que el manejo de imágenes (es decir, capturas de pantalla) fuera más fácil. Y aunque tener la capacidad de buscar es esencial, creo que la búsqueda de MediaWiki a menudo pierde páginas. Tal vez sea solo una cuestión de aprender a buscar mejor (lo que frustra el propósito de tener una manera simple para que otros hagan su trabajo)

En este momento estamos en conversaciones para trasladar todo a MS Sharepoint , aunque no necesariamente a su wiki. Creo que Sharepoint puede realizar una búsqueda completa de documentos de una manera que niega algunas de las ventajas de una wiki, así que veremos a dónde va esto.

(aunque no espero el proceso de portar toda nuestra documentación actual :))

Estamos usando una wiki. Claro que la sintaxis tardó un poco en acostumbrarse, pero la que estamos usando (twiki) almacena sus datos completamente como archivos de texto. Esto nos permite leerlos fácilmente en caso de un desastre, ya que podemos restaurarlos en cualquier lugar, y buscarlos desde la línea de comandos a través de grep, y leerlos en cualquier editor de texto que nos guste.

Cada servidor tiene una página, con una colección estándar de subpáginas para información de gestión de cambios, inicio / apagado, y notas de configuración, así como dns, firewall e información de activos.

Nos estamos preparando para pasar a alguna versión de un servicio Sharepoint para tratar de sacarnos de una mezcla de documentos de Word distribuidos en tres servidores y quién sabe cuántas carpetas. Actualmente, tenemos una hoja de cálculo masiva de Excel que contiene hipervínculos a los documentos que se describen en ella.

No es la mejor manera de hacerlo, pero cuando la compañía comenzó, nunca planearon cómo manejar la documentación interna y dejaron a cada grupo decidir cómo clasificar y almacenar su propia documentación como mejor les pareciera. Ahora, estamos tratando de fusionarnos en un sistema unificado, que estará en torno a una de las ofertas de Sharepoint.

En la ONG donde trabajo, solo utilizamos archivos de texto ubicados en una carpeta para procedimientos críticos. Personalmente, como híbrido de administrador de sistema / desarrollador web, he estado utilizando una base de conocimiento de archivos de texto dispersos en un directorio de árbol, ese es mi Memex y escribo casi todo en él (personal, trabajo, etc.). Este esquema es muy fácil de administrar usando Jedit, una verdadera navaja suiza para el procesamiento de texto, he encontrado que su complemento de esquema, plegado de código y características de hiperesearch son indispensables. Todo esto con copia de seguridad de rsync a un servidor remoto accesible mediante ssh.

Combínalo con la extensión Makelink Firefox y tendrás el administrador de marcadores perfecto.

Usamos flexwiki , que es un dotnet y de código abierto.

Erm ... ¿qué tal Fogbugz? :)

Estamos utilizando ScrewTurn para contenido y SharePoint para almacenar documentos / imágenes.

Hay algunas cosas interesantes aquí - Me gusta el de las contraseñas en una caja fuerte.

Utilizamos una combinación de archivos de texto para realizar búsquedas rápidas con grep. Y SharePoint para una colección más organizada de documentación detallada (diagramas de Visio, etc.).

Como clientes de Google Apps (Enterprise), utilizamos los sitios de Google: su "sabor" wiki. Fácil de usar y hemos tenido una gran adopción por parte de administradores y desarrolladores.

No vi esta pregunta antes de responder otra pregunta , pero aquí vamos.

Utilizamos una serie de herramientas y métodos.

• Especificaciones funcionales para componentes de infraestructura y software.
• Dos wikis de confluencia . Uno para documentación corporativa interna (políticas, procedimientos, infraestructura interna y TI, etc.) y otro para nuestros productos de software de código abierto.
• Pruebas de RSpec y pepino . Nuestro software está escrito principalmente en Ruby, y practicamos BDD / TDD , por lo que las pruebas de especificación conducen el código real y también documentan.
• Documentación de código en línea. Usamos marcado RDoc en los comentarios de código.
• Gestión de configuración declarativa ( Chef ). Todos nuestros servidores se administran con Chef, que "documenta por sí mismo" a través de recursos delicados en recetas y libros de cocina.

Nos gusta Confluence porque es muy flexible y potente y tiene características completas, además de estar vinculado al software de gestión de tickets que nos gusta, Jira .

En compañías anteriores en las que he trabajado, he usado una variedad de herramientas y métodos y muchos han tratado de quedarse con un solo recurso general (como un Wiki) para todo. El problema con eso es documentar varios temas con una sola herramienta que no es especialmente adecuada para cubrir ese tema, lo que significa que muchas cosas no se documentarán en absoluto, porque es difícil migrar la información. Como geek de Unix / Linux, creo que cada tarea requiere una herramienta específica, y esa herramienta debería encajar muy bien en esa tarea.

Esta pregunta es muy bien un duplicado de esta y moví mi respuesta allí.

Hago la mayor parte de la documentación para mi empresa, y el formato que se estableció cuando comencé a trabajar aquí era MS Word para originales editables, exportados a PDF para versiones generales de solo lectura. Funciona bastante bien para proyectos donde solo una persona está actualizando el documento, y dado que esa persona generalmente soy yo, la gerencia no ha visto la necesidad de cambiar.

Comenzamos a documentar nuestros errores y las próximas tareas con Trac , mientras utilizamos una extensión de "Revisión por pares" para las revisiones de código. Eso ha tenido una gran aceptación por parte de nuestro equipo porque es sencillo colaborar y es fácil de navegar. Algunos otros miembros del equipo han expresado su deseo de comenzar a colaborar más con las especificaciones, los procedimientos de prueba y los manuales, por lo que estamos buscando en DocBook / XML exportado a PDF para documentación pública como manuales, y páginas Trac WIKI para documentos internos como especificaciones y procedimientos de prueba.

En mi opinión, los problemas más importantes al elegir un formato de documentación son:

1. ¿Es fácil de crear?
2. ¿Es fácil de mantener?
3. ¿Es fácil de mantener si alguien más lo escribió?
4. ¿Se puede exportar / convertir a otros formatos sin mucha molestia?

1-3 hacen que mi vida sea más fácil y son importantes para producir documentación rápidamente sin volverme loco. Creo que el cuarto es el más importante para el cliente, porque los formatos cambian continuamente. El formato Microsoft Word 2003 no estará disponible para siempre, y tampoco nuestra implementación actual de PDF. Necesito asegurarme de que todos nuestros clientes puedan leer nuestros documentos, sin importar cuál sea su sistema operativo o el lector de documentos que elijan.

Utilizamos MediaWiki con varios complementos, incluido SemanticMediaWiki. SMW es bueno porque convierte nuestra instalación de MediaWiki en una gran base de datos relacional de forma libre que se puede consultar a voluntad. ¿Necesita saber en qué servidor está un sitio web? Visita su página. ¿Necesita saber qué sitios web están alojados en un servidor? Ejecute una consulta y seleccionará los nombres de las páginas según la etiqueta adecuada en la página de cada sitio web.

No responderé con un sistema de documentación que he usado, sino con algo que he visto usado y que encuentro muy bueno: http://stackexchange.com/

stackexchange es la plataforma de preguntas y respuestas que se ejecuta bajo serverfault (bueno, técnicamente no es exactamente lo mismo, pero para nuestro propósito aquí podemos suponer que es lo mismo).

Fogbugz lo usa .

Hay una publicación de blog interesante de un empleado de Fogbugz donde encontré estas citas:

Para todos los propósitos fuera de las especificaciones del producto, creo que los wiki corporativos y los formularios de discusión han recibido un golpe fatal.

...

Desde que comenzamos a usar FogBugz.StackExchange.com como nuestra plataforma de soporte, nunca he respondido la misma pregunta dos veces. Incluso tenemos un servidor SE interno que utilizamos para preguntas y respuestas no públicas, y los mismos principios se aplican allí.

Utilizan stackexchange para la base de conocimiento orientada al cliente y la base de conocimiento interna.

Estoy interesado en ver si tales plataformas de preguntas y respuestas de intercambio de conocimiento reemplazarán a las wiki corporativas.

En mi empleador anterior, utilizaba archivos de Word, Excel y Visio recopilados en una carpeta. Una copia impresa de todo estaba guardada en una carpeta en mi escritorio. Yo era la única persona de TI, por lo que había poca necesidad de que alguien más tuviera acceso a la información.

En mi empleador actual, utilizamos Macola ES de Exact Software, pero todavía prefiero escribir mi documentación en Word y subirla a Macola como archivo adjunto que usar el editor de documentos incorporado.

En mi lugar de trabajo, solté ScrewTurn Wiki en uno de nuestros servidores de desarrollo de Windows y lo conecté a nuestro SQL Server. Funciona realmente bien, se ejecuta rápidamente y principalmente se mantiene fuera de nuestro camino para la documentación. En las dos semanas desde que se implementó, ya hemos agregado unas 60 páginas de información, y es solo para nuestro equipo (~ 10 personas).

Hasta el momento, mantenemos información sobre proyectos actuales y pasados ​​allí, y hemos comenzado a agregar información sobre las aplicaciones, como cómo construirlas desde cero, URL y otra información importante para los desarrolladores nuevos en el equipo.

Una de mis páginas favoritas en la wiki ha sido la página de herramientas y bibliotecas. Allí, comenzamos a agregar información sobre nuestras herramientas y bibliotecas de productividad favoritas que utilizamos mucho, un ejemplo de lo cual es grepWin para la búsqueda de texto en Windows.

Recomendaría revisar la gama completa de wiki disponibles y encontrar una que se adapte a su uso previsto, funcionalidad y entorno de implementación. Elegí ScrewTurn porque es fácil de usar, y teníamos un montón de espacio libre en nuestro WinServer local, pero YMMV.

Estamos utilizando Confluence como wiki y sharepoint para documentos en algunos casos. Creo que el formato wiki en línea es el preferido cuando necesita compartir esta información de manera muy amplia y lo que es mucho más importante cuando los documentos se van a editar y actualizar con mucha frecuencia. Así que creo que es mejor poner los artículos de la base de conocimiento en wiki.

Actualmente estamos trasladando nuestra información de varios documentos distribuidos por la red a dos ubicaciones:

1. Un wiki disponible en nuestra intranet
2. Una copia de la información relacionada con un servidor en particular en ese servidor / directorio raíz.

Para diagramas de red, Bloc de notas de red .

Además, mientras graba el qué, recuerde registrar por qué algo está configurado como está. Esto ayuda a evitar que las ideas que parecen una buena idea se conviertan en errores.

Descubrimos que MediaWiki ha sido un comienzo lento, pero una vez que la gente fuera de TI se enteró de lo fácil que fue agregar comentarios, cambios, ediciones, etc., se volvió indispensable. Los desarrolladores lo están utilizando para documentación interna, departamento de instalaciones. para publicar avisos, etc. Ha crecido más allá de ser simplemente una herramienta de documentación de TI.