¿Busca una estructura de mejores prácticas para configurar una wiki para desarrolladores?

Dirigiré un equipo que no ha tenido el mejor historial de documentación, comunicación e intercambio de conocimientos. Me gustaría tener un marco configurado para que sea más fácil para el equipo comenzar en esta área.

No se concentre demasiado en obtener una estructura perfecta por adelantado, mejor déjela crecer orgánicamente . Lo que importa es la cultura y el proceso de comunicación.

A continuación hay algunos consejos para mantener el wiki del equipo.

fundamentos

retroalimentación de valor

Solicite, recopile y registre cualquier comentario que pueda recibir: correo, comentarios de la página wiki (por cierto más conveniente), mensajería, conversación.

• grabación de comentarios

  • P: ¿qué sucede si actualmente no tengo tiempo para procesar correctamente la información?
  • R: guárdelo en la página tal como está, para su procesamiento futuro y oculte a los lectores habituales de la siguiente manera:{excerpt:hidden=true}information to be processed later{excerpt}

• procesamiento de comentarios

  • Intenta hacerlo lo más rápido posible. Los detalles y el contexto que le parecen obvios a usted o al remitente en este momento, se pueden olvidar un día, una semana o un mes después.  
  • considerar soluciones alternativas a los problemas señalados en la retroalimentación. Ejemplo:
    • (retroalimentación) oye, la información que necesito se mezcla con una inútil
    • (acción incorrecta) OK, elimino cosas que no necesitas
    • (acción correcta) OK, dividiré la información en uno de sus intereses y el resto que podría ser de interés para otra persona

manejo de sugerencias que implican trabajo a largo plazo

• P: ¿qué sucede si la sugerencia es como decir "recopilar y reorganizar todos los datos relevantes documentados en otras mil páginas"?
• R: agregue una sección TODO-s a su página (si aún no está allí) y registre la sugerencia en esta sección. Más tarde, puede usarlo también para seguir su progreso
  update DD.MM.YYYY: 475 pages of 1000 are processed

manejo de sugerencias que te parecen incorrectas

Nota al margen nunca está de más pedirle al remitente de la sugerencia una aclaración. Sin embargo, es mejor que hagas tu parte del trabajo primero:

• verifique el historial de la página, teniendo en cuenta la fecha de revisión. Siempre existe la posibilidad de que el remitente señale el problema desde una versión anterior que ya está corregida
• mire más de cerca la página / sección mencionada y pregúntese, ¿qué podría hacer que él / ella piense de esa manera?
• (después de un pequeño entrenamiento con truco como el anterior) descubrirá que en la mayoría, si no en todos los casos, hay un área distinta para mejorar allí.
  • Imagine, por ejemplo, un usuario quejándose de información faltante que en realidad está presente en algún lugar de la página. A pesar de verse mal en la superficie, tal queja a menudo indica un problema grave en la página: a saber, que es difícil encontrar alguna información importante. Darle la visibilidad que merece mejorará la página.

mejor rápido que perfecto

Confíe en la revisión y comentarios. Si algo realmente necesita corrección, el tiempo lo resolverá por usted

• Esto también se aplica a la autoevaluación. Grabe el borrador de lo que desea poner en la página y revíselo usted mismo una hora (o día o semana) más tarde; este truco puede hacer maravillas
• no pierdas el tiempo haciendo las cosas perfectas al primer intento, es imposible
  • registre la información tan pronto como parezca apenas aceptable y solicite a los interesados ​​que la revisen

ser audaz

Sea audaz al actualizar páginas: solucione problemas , corrija la gramática, agregue datos, asegúrese de que la redacción sea precisa, etc.

• Lo anterior se basa en el principio de Wikipedia y se explica mejor, bueno, en Wikipedia
  • ... pero tenga cuidado: cuide el bien común y no edite imprudentemente: una aclaración al principio anterior,
    también explicada en Wikipedia

avanzado

estar agradecido

Las personas que brindan comentarios son un activo valioso, agradézcales. Estas personas se tomaron su tiempo y esfuerzo no solo para leer su página, sino también para proporcionar sus comentarios. La gran mayoría de sus usuarios no serán tan generosos con usted. Quienes comparten sus pensamientos son "la crema" de su audiencia, estén agradecidos por su contribución.

explicar TLA-s

Si no puedes entender qué es TLA? - tienes el punto

• use enlaces para eso si es posible: TLA

registrar respuestas a preguntas

Respeta el tiempo de los demás - registra las respuestas

• Puede tomar un segundo para responder a la pregunta, pero ¿piensa en el tipo que la hizo? (S) se tomó el tiempo de leer su página, tratar de encontrar la respuesta, contactarlo y esperar su respuesta. Si registra la respuesta en la página, ahorrará todo ese tiempo para el próximo tipo que tenga esta pregunta.
• Registre las respuestas a sus propias preguntas. Lo que no está claro para usted, podría no estarlo para el próximo lector.

usar signos de interrogación

En caso de duda, use signos de interrogación

• Sintaxis de confluencia como ejemplo: (?) Ejemplo:<this info> needs checking
• de esta manera, cualquier lector puede ver claramente qué tipo de información necesita; hay muchas posibilidades de que alguien pueda ayudarlo a aclarar cosas

los enlaces son tus amigos

• DRY - no trate de copiar la información cuando se puede proporcionar el enlace en su lugar
• aprender a resumir cuando sea necesario
  • algún enlace - oye, ¿qué es esto?
  • algún enlace : Wikipedia, la enciclopedia gratuita que cualquiera puede editar.

las imágenes importan

• Cuando tenga tiempo, revise su página y pregúntese si es fácil para el lector obtener los puntos que está dispuesto a hacer.
• Puede ser bastante difícil encontrar sustancia en una corriente de conciencia no estructurada

  ^{...Le di todo el placer que pude llevarlo hasta que me pidió que dijera que sí y no respondería primero, solo miraba el mar y el cielo. Estaba pensando en tantas cosas que no sabía de Mulvey, el señor Stanhope y Hester y padre y el viejo capitán Groves y los marineros que vuelan todos los pájaros vuelan y digo agacharse y lavar los platos lo llamaron en el muelle y el centinela frente a la casa del gobernador con la cosa alrededor de su casco blanco pobre diablo medio asado y las chicas españolas riéndose en sus chales y sus altos peines y en las subastas de la mañana, los griegos y los judíos y los árabes y el diablo saben quién más de todos los extremos de Europa y la calle Duke y el mercado de las aves cacareando fuera de Larby Sharons y los pobres burros medio dormido y los vagos tipos de las capas dormían a la sombra en los escalones ylas grandes ruedas de los carros de los toros y el viejo castillo de miles de años sí y esos moros guapos, todos de blanco y turbantes como reyes que te piden que te sientes en su pequeña tienda y Ronda con las viejas ventanas de las posadas Dos ojos que miraban escondieron una red para que su amante besara el hierro y las vinotecas medio abiertas por la noche y las castañuelas y la noche en que perdimos el bote en Algeciras, el vigilante sereno con su lámpara y O ese horrible torrente en el fondo O y el mar el mar carmesí a veces gusta el fuego y las gloriosas puestas de sol y las higueras en los jardines de la Alameda, sí, y todas las callejuelas raras y las casas rosadas y azules y amarillas y los jardines de rosas y las jessaminas y geranios y cactus y Gibraltar como una niña donde yo estaba una flor de la montaña sí, cuando me pongo la rosa en el pelo como elLas chicas andaluzas usaban o debería usar un sí rojo y cómo me besó debajo de la pared árabe y lo pensé tan bien como otro y luego le pregunté con los ojos que volviera a preguntar sí y luego me preguntó si quería decir sí, mi flor de montaña y primero puse mis brazos alrededor de él sí y lo atraje hacia mí para que pudiera sentir mis senos todo perfume sí y su corazón se estaba volviendo loco y sí dije que sí lo haré sí.}

relájate y diviértete

Tenga en cuenta que, por lo general, no se requiere que los lectores de su página sean muy serios.

• cuando sientas que es apropiado divertirse, tómalo

podredumbre de enlace de lucha

• ¿Estás dispuesto a mover alguna página o recurso?
  Bien, solo piense en los chicos que tienen enlaces a él en algún lugar de sus marcadores, archivos de correos electrónicos, documentos, etc.
• Cuando (re) mueva la página o un documento, mantenga un marcador de posición donde se ubicaba anteriormente, para ayudar a los visitantes a comprender qué le sucedió y dónde ir en su lugar
  • <this page> has been moved to <that page>
  • <this document> has been removed because of <the reason>

Referencias para lecturas adicionales

• Políticas y pautas de Wikipedia
• Guía de notación de confluencia
• Patrones Wiki

Primero, es importante elegir un buen Wiki. Elige uno que:

1. Está bien mantenido y tiene buen apoyo.
2. Admite autenticación de usuario y tiene control de acceso a documentos o espacios de nombres.
3. Realiza un seguimiento de los cambios en los documentos y proporciona un historial.
4. Permite la notificación por correo electrónico de cambios en el documento.
5. Tiene un buen editor, preferiblemente WYSIWYG, y admite listas, tablas y carga de imágenes.

Lo más importante que necesita un equipo de desarrollo Wiki es un "jardinero": alguien responsable de determinar el diseño y la estructura de los documentos en Wiki. No tiene que ser un papel a tiempo completo, pero el jardinero debe tener un inglés fuerte y una aptitud para explicar bien las cosas. El jardinero debe crear plantillas estándar para páginas, convenciones de nombres y determinar qué espacios de nombres son necesarios.

El jardinero no es responsable de crear el contenido, sino de hacer cumplir su estructura. Por ejemplo, si alguien realiza un cambio en un producto, el jardinero no es responsable de realizar el cambio en el Wiki. Sin embargo, el jardinero es responsable de asegurarse de que se realice el cambio y de que se realice de acuerdo con las pautas (no solo pegado en una página separada, sin vincular, por ejemplo). El jardinero puede revisar los cambios o delegarlos a otra persona.

Es importante estructurar el Wiki para satisfacer las necesidades de la audiencia en lugar de las necesidades de quienes crean contenido. Por ejemplo, si tiene una interfaz de usuario dedicada o un equipo de seguridad o localización para el desarrollo de software, no coloque su información en secciones separadas. Póngalos en la misma sección que los desarrolladores están viendo. Tener todo junto hace que sea mucho más fácil de encontrar, asegura que las cosas no se pierdan e identifica el contenido desactualizado más rápido.

Un Wiki necesita un cambio de mentalidad. Muchas compañías están acostumbradas a que la información se les imponga. Un Wiki permite a los consumidores de la información modificarla. Esto debe ser altamente recomendado (y recompensado si es necesario). Si la inexactitud es una preocupación, haga que los revisores configuren el Wiki para enviarlas por correo electrónico cuando se realicen modificaciones.

Un Wiki de desarrollo necesita una estrategia para manejar el control de versiones. Si tiene un conjunto de documentos para la versión 1.0, ¿qué sucede cuando se lanza la versión 2.0? Algunos de los documentos para la versión 1.0 aún pueden aplicarse a 2.0, pero algunos pueden ser reemplazados. ¿Qué sucede si se realiza un cambio en un documento 1.0 después del lanzamiento de 2.0?

Un Wiki necesita alguna forma de medir el éxito. ¿Cuántas personas lo están usando? ¿Encontraron lo que estaban buscando? No necesariamente necesita un cuadro grande de calificación y comentarios desagradables en la parte inferior de la página, pero un simple enlace "Enviar un correo electrónico a un humano sobre esta página" puede ser útil.

Por último, los patrones de uso de un Wiki cambiarán con el tiempo. Recuerde revisar los estándares periódicamente para asegurarse de que aún satisfacen las necesidades de Wiki.

Si bien es una buena idea que todas las páginas wiki del proyecto sigan un tema similar para que todos sepan dónde encontrar las cosas, esto realmente no resolverá el problema de que los desarrolladores no actualicen las páginas.

Debe encontrar una manera de hacer que sus desarrolladores vean suficientes beneficios al hacer estas cosas que lo impulsan y quieren que se haga. De lo contrario, simplemente lo verán como otra carga burocrática de arriba hacia abajo de la que podrían prescindir.

He estado en esta situación, tanto donde el wiki era un completo desastre como donde estaba altamente organizado y formal. El estado de la wiki no afectó el nivel de interés de los desarrolladores.