documentation - open - Hacer que los desarrolladores usen una wiki

wiki open source (13)

Creo que la mayoría de las respuestas hasta ahora son acertadas: cuanto más lo ocultes, mayor será el volumen de información útil, de forma lenta pero segura las personas comenzarán a usarla de forma natural.

El otro enfoque que podría usar es el siguiente: sugiera que cada vez que alguien haga una pregunta sobre el proyecto a otro miembro del equipo, responda la pregunta como siempre, pero también agregue la respuesta a una sección del Wiki. Esto puede tomar unos minutos más, pero significará que la próxima vez que alguien haga la misma pregunta (lo que inevitablemente harán), puede ahorrar tiempo apuntándolos al Wiki. Esto, a su vez, debería ayudar a las personas a comenzar a utilizar Wiki como primera fuente de información y ayudar a la adopción general.

Trabajo en una aplicación compleja donde diferentes equipos trabajan en sus propios módulos con un grado de superposición. Hace un tiempo, obtuvimos una instancia de Mediawiki configurada, en parte a petición mía. Me cuesta trabajo hacer que la gente realmente lo use, y mucho menos contribuir.

Puedo ver muchos beneficios al compartir información. Al menos puede reducir los tiempos reinventamos la rueda.

La wiki no es muy estructurada, pero no estoy seguro de que sea un problema, siempre que pueda buscar lo que necesita.

¿Algún consejo?

Encuentra elementos "adhesivos" (sub-3 pg. Docs / diagrams / etc) algo que el equipo parece estar creando una y otra vez y publícalo en la wiki. Asegúrese de que todos tengan acceso a la wiki y sepan que está allí; configure un mecanismo de notificación si es posible. Con un poco de suerte, la próxima vez que tengan acceso, en lugar de desenterrarlo del control de la versión o de sus máquinas, deberían acceder al wiki. Si todavía no lo hacen, intente ver si el equipo tiene suficiente holgura para usar realmente la wiki. Los problemas de Subtler pueden estar debajo de su renuencia.

He hecho algunas ventas e incluso he realizado algunas sesiones de entrenamiento. Creo que algunas personas están desconectadas por la falta de edición WYSIWYG y la capacidad de pegar texto formateado de Word o Outlook. Sé que hay algunas herramientas para solucionar estos problemas, pero siguen siendo barreras.

Hay algunas áreas donde la wiki se usa para registrar ciertas áreas, pero las personas que actualizan esas no están haciendo otra cosa con ella.

Usaré la wiki para documentar mi área especializada, independientemente de que actúe como una conveniente extensión cerebral. Al comenzar un nuevo desarrollo lo uso como un bloc de notas para ideas que puedo ampliar a medida que avanza.

Ayudaría si la gerencia le diera algún apoyo vocal, incluso si no se lo hace obligatorio.

Hemos estado usando una wiki de una forma u otra desde hace un tiempo, pero a las personas les toma un tiempo subir a bordo. Es posible que descubras que serás el único que escribe artículos durante algún tiempo, pero que a la larga te aceptarán otras personas.

Si alguien envía un correo electrónico que contiene información relacionada con el proyecto, entonces, ayúdelos a orientarlos en la dirección de la wiki y continúen haciéndolo, deben obtener la pista.

Tenemos un portal de SharePoint y utilizamos el wiki a partir de allí: lo personalizamos con nuestra propia marca para que "se vea como la pieza". Realmente creo que esto ha ayudado a mejorar su aceptación.

Asegúrese de que todos sepan que el wiki es incluso más informal que el correo electrónico ... porque habrá un "factor de miedo" que las personas pensarán que todo lo que agreguen al wiki será analizado en exceso.

No puede obligar a los desarrolladores a hacer algo para lo que no tienen un incentivo de usar; Desafortunadamente, los wikis, al igual que la documentación (bueno, de hecho, los wikis son documentación) rara vez tienen un valor "genial" para los desarrolladores. Además, ya están metidos en el trabajo de desarrollo. ¿Podrías realmente molestarlos con una wiki?

Una vez dicho esto, las personas que presionaron por la wiki (por ejemplo, usted) deberían ser los principales responsables de actualizarlo, y realmente tendría mucho trabajo para usted si lo toma en serio.

También puedes probar el ff:

No es muy estructurado, se dice: mucha gente se desconecta de los wikis mal estructurados (difíciles de buscar / navegar). Entonces quizás puedas arreglar eso primero
Tal vez pueda pedirle a los desarrolladores principales / gerentes de proyecto que lo completen con cosas que son problemas para ellos: cosas como convenciones de códigos y diseño de API para su proyecto en particular
Predique con el ejemplo: documente religiosamente su parte del sistema. Establecer un precedente puede alentar a otros a hacer lo mismo

Vende la idea de usar la wiki a los desarrolladores. Has identificado algunos beneficios, compártelos con los desarrolladores. Si pueden ver que obtendrán algo de valor de esto, comenzarán a usarlo.

Ventajas del ejemplo de What Is a Wiki

Es bueno para anotar ideas rápidas o más largas, dándole más tiempo para la redacción y edición formal.
Colaboración instantánea sin enviar documentos por correo electrónico, manteniendo al grupo sincronizado.
Accesible desde cualquier lugar con conexión a Internet (si no le importa escribir en los formularios de texto del navegador web).
Su archivo, porque se guarda la revisión de cada página.
Emocionante, inmediato y empoderador: todos tienen algo que decir.

Eche un vistazo a los consejos en http://www.ikiw.org/ Grow your Wiki

Solo para agregar a algunos de los excelentes consejos que se ofrecen aquí ...

Como desarrollador de una pequeña empresa que generalmente contrata trabajo en el rango de 6 a 24 meses, encuentro que mi tiempo a menudo se divide entre informes de desarrollo y de estado de redacción (¡justo al lado de escribir documentación, solo que peor!) un wiki para escribir pensamientos y notas desorganizados a medida que avanzamos ha hecho que la redacción de informes sea mucho menos dolorosa (sin dolor, MENOS, pero mejor de todos modos).

Además, si ya estás en el mundo de Mediawiki, es posible que desees consultar SemanticMediawiki . Le permite llevar la organización de sus datos a otro nivel al etiquetarlo semánticamente. Eso no significa mucho en sí mismo, lo sé, pero puedo decirle (por ejemplo) que puede mejorar drásticamente la relevancia de los datos devueltos por las búsquedas. Definitivamente vale la pena echarle un vistazo.

Me cuesta trabajo hacer que la gente realmente lo use, y mucho menos contribuir.

Una de las formas más sencillas de hacer que las personas contribuyan a una wiki es que proporcionen contenidos de una manera adecuada para la wiki, es decir, lo que publiquen utilizando sus canales habituales de comunicación (grupos de noticias, listas de correo, foros, seguimiento de problemas). , chat), es básicamente adecuado para su inclusión en la wiki.

Para que otros (usuarios / voluntarios) simplemente puedan tomar dichos contenidos y ponerlos en la wiki.

Esto suena más complicado de lo que realmente es, se trata principalmente de generalizar preguntas y respuestas, de modo que no formen necesariamente parte de una conversación, pero pueden ser comprensibles, significativas y útiles de manera independiente.

Por ejemplo, una pregunta como la siguiente:

¿cómo hago para que git clone un repositorio remoto?

Se puede responder así:

Hola, solo usa git clone git: // ...

Pero las preguntas también pueden responderse en un estilo menos personal:

Para clonar un repositorio git, querrás usar el parámetro clone para git: git clone git: // ...

Lo que trato de decir es que la mayoría de las discusiones en un proyecto pueden y deben usarse fácilmente para convertirse en documentación eventualmente. Con este tipo de mentalidad, su documentación puede crecer con bastante rapidez. Solo necesita que las personas tengan en cuenta que la información útil debe proporcionarse idealmente de manera que sea adecuada para la inclusión de wiki.

He sido testigo de varias instancias en las que los proyectos de código abierto comenzaron a utilizar este enfoque hasta cierto punto y mientras algunas personas (en su mayoría usuarios nuevos) se quejaban de que las respuestas no eran muy personales, el cuerpo de documentación aumentaba continuamente, porque otras personas simplemente monitoreaban tales discusiones y comenzó a copiar / pegar tales respuestas al wiki.

Básicamente, esta es una de las formas más sencillas de lograr que las personas contribuyan a una wiki, sin necesidad de que la utilicen ellos mismos, lo único que se requiere de ellos es un cambio en el modo de pensar.

Si los desarrolladores aún necesitan mantener documentación ''real'' (es decir, documentos de Word), no veo forma de duplicar eso en una Wiki.

No tiene sentido que la gente escriba dos veces
Cualquier información duplicada es propensa a perder sincronía, pronto.

Lo que mi cliente actual ha hecho es mover todo esto a Wiki. Así que solo doy un documento una vez, y lo hago en Wiki.

Esto está bien. Trabajar con Wiki es más tedioso que con Word, pero al menos el documento está en línea y otros pueden mezclarse y combinarse con él.

Otra solución de trabajo (imho) sería almacenar documentos junto con la fuente, en subversión. Pero luego el sistema de fusión debe ser capaz de manejar textos enriquecidos, etc. también. No sé si existe alguna solución para eso (aparte de usar HTML o LaTex, que en realidad no serían malas selecciones).

Algunos consejos:

Cada vez que alguien envíe información por correo electrónico que realmente debería estar en una wiki, haga una página para ese tema y agregue lo que ponen en el correo electrónico. Luego responda: "Gracias por esa información, la he puesto en el wiki aquí para que sea más fácil de encontrar en el futuro".

Del mismo modo, si tiene información que debe compartir que debe estar en la wiki, colóquela allí y simplemente envíe un correo electrónico con un enlace a ella, en lugar de enviar correos electrónicos a otras personas.

Cuando le pidas información a las personas, fíjala de modo que incluir dicha documentación en el wiki se considere la predeterminada o estándar: "Busqué en el wiki pero no pude encontrarlo. ¿Has puesto esa información allí?"

Si usted es el "campeón de la wiki", asegúrese de que otras personas sepan cómo usarlo, por ejemplo, "¿Ya revisé cómo crear una página nueva?"

Edite la barra lateral para asegurarse de que sea relevante para su trabajo.

Use las plantillas de estilo "nav box" en las páginas relacionadas para una navegación más fácil.

Ponga algo como {{Special: NewPages / 5}} en la página principal, o cambios recientes, para que las personas puedan ver la actividad.

Echa un vistazo a los cambios recientes cada pocos días o semanas, y si notas que alguien agrega información sin que te pinchen, envíales un correo electrónico o visítanos y dales un pequeño cumplido.

Generalmente buenos consejos aquí. Me gustaría agregar:

Realmente necesitas un campeón : alguien empujando esto a los desarrolladores y la administración (sin ser insistente , ¡eso es un desafío!) Y brindando asistencia y tutoriales cuando sea posible. Esta persona también necesita ser un compañero (por lo tanto, un desarrollador compañero, no alguien en un departamento de TI remoto) y realmente centrado en el cliente, es decir, listo para realizar cambios cuando se le solicite.
Hablando de cambios, algunas personas aquí dicen que los wikis no están estructurados . Estoy en desacuerdo. Nuestra instalación de MediaWiki está estructurada usando categorías, particularmente con dos extensiones: WarnNoCategories (para requerir que los usuarios agreguen una categoría al guardar una página) y Category Tree para mostrar cómo encajan todas las categorías (puede vincularse desde la barra lateral). Tengo más consejos sobre cómo mantenemos este umbral bajo, si estás interesado.

Como mencioné antes , una Wiki es muy desorganizada.

Sin embargo, si ese es el único argumento de sus desarrolladores, invierta un poco de esfuerzo para crear una página de índice simple y mantenerla actualizada (hágalo usted mismo o solicite a las personas que vinculen sus contribuciones al índice). De esta forma, la Wiki podría convertirse en una colección de documentación muy buena y bastante completa para todo su trabajo.