En las clases hemos visto como utilizar el archivo README.md para mostrar la documentación del proyecto, con el tiempo esta práctica ha ganado cada vez más adopción por su sencillez, pero eso no es la única manera de crear documentación.
Para ello existe dentro de Github la opción de crear una Wiki en donde puedes generar un nivel más estructurado de documentación. Puedes ver la sección de Wiki en tus proyectos en la sección superior del portal de Github.
Si seleccionas esta opción entonces podrás ver un botón que te invita a crear tu primera página, hazlo presiónalo.
El formulario te da la opción de crear una nueva página a la que llama Home lo que es una gran opción, puedes usar esta página para mostrar la documentación inicial, pero también la puedes usar como un índice para poder llevar a tu lector a diferentes secciones y eso es lo que vamos a hacer. Escribe lo siguiente en tu formulario.
# ¡Bienvenido a la wiki!Aquí podrás encontrar todas las secciones para poder implementar tu proyecto de manera rápida y simple.
## Índice de navegación
[Explicación del proyecto](/proyecto.md)
Si presionas el botón de guardar los cambios, el resultado de esta primera edición es igual al de esta imagen.
Repite la misma operación, ahora con una nueva página llamada Proyecto, en su descripción puedes agregar cualquier contenido, en la imagen que sigue puedes ver un ejemplo de como debe lucir tu nueva página.
Si guardas los cambios, entonces el resultado de la estructura de tu wiki lucirá de la siguiente manera.
Comienza a crear algunas páginas, no te diré cuantas ni con qué nombres para que te diviertas, lo que sí haré es mostrarte como luce mi wiki al final.
Ahora vuelve a tu página Home en donde agregaste un poco de texto y además un enlace, en la esquina superior derecha hay un botón con el que puedes editarla. En el código markdown de aquí abajo podrás ver una manera fácil en la que puedes navegar entre secciones.
# ¡Bienvenido a la wiki!Aquí podrás encontrar todas las secciones para poder implementar tu proyecto de manera rápida y simple.
## Índice de navegación
[Explicación del proyecto](./Proyecto)[Arquitectura](./Arquitectura)[Documentación](./Documentación)
Con este índice es fácil que tus usuarios puedan navegar entre las secciones de una manera cómoda, lo que estaría fenomenal es que ahora les facilites a tus usuarios volver a la sección principal en cada una de tus secciones para que la navegación se vuelva cíclica y así les sea muy fácil moverse entre todas las secciones. ¿Cómo harías eso?
Volvamos a la pantalla principal de la wiki y observa que debajo del menú de páginas está una sección que te permite crear una barra lateral personalizada, selecciona esta opción.
Al hacerlo notarás un formulario idéntico a los anteriores, solo que con un título diferente en donde podrás personalizar todos los detalles de la barra lateral, intenta copiar y pegar aquí el mismo markdown que acabamos de usar en la página Home. ¡Oh! Cierto, no cambies el título, la palabra _Sidebar es lo que permite que Github sepa que estamos hablando de una barra lateral y no de otra sección más.
Guarda tus cambios y disfruta de tu nueva barra de navegación.
Una característica superinteresante es que puedes clonar esta wiki dentro de tu entorno local sin mayor problema, observa que hacer esto significa que solo vas a clonar todos estos documentos y no vas a hacer lo mismo con el repositorio lo que se me hace superinteresante porque puede ser que el portal de Github sea fantástico, pero no tanto como para pasar ahí horas leyendo documentos por lo que de esta manera puedes hacerlo desde tu lector de documentos Markdown favorito.
¡Invierte tiempo en tus wikis!. Visita las de otros proyectos y toma muchas ideas de ahí, practica mucho con tu documentación aprendiendo a usar el lenguaje Markdown y cuando tengas una wiki fantástica no olvides compartirla con todos nosotros.
En este link pueden hacer esa portada, queda brutal
Capsule-Render
este es mi perfil pero no se que tal se ve
your cover is amazing, i just inspired on yours to make mine, thanks a lot Danny
Clase 23 - Uso de Wikis
¿Qué otra alternativa tenemos en GitHub para crear documentación a parte del archivo READM.md?
Wikis.
¿En qué lenguaje debemos escribir las Wikis de GitHub?
Markdown.
¿Desde qué lugar podemos crear wikis en GitHub?
Esto lo podemos hacer desde el home de alguno de nuestros repositorios. Concretamente en el menú superior.
¿Podemos clonar un wiki de GitHub a nuestro entorno local?
Sí.
Le ayudé a mi novio a crear su REDME muy sencillo.
¿Feedback?
Ponerlo en inglés
Solo tener fijado en el GitHub los repositorios que están vinculados con las tecnologías que está usando (Python y PowerBI) no HTML.
El archivo README.md es un archivo de texto en formato Markdown que se utiliza para proporcionar información sobre un proyecto en GitHub. Suele incluir detalles como el propósito del proyecto, cómo instalarlo, cómo usarlo y cómo contribuir. Es una herramienta crucial para la documentación, ya que ayuda a otros desarrolladores a comprender rápidamente el proyecto. Es común verlo en la raíz del repositorio y es uno de los primeros archivos que los usuarios revisan al explorar un proyecto.
Comparto mi README que hice inspirandome en varios estudiantes
Qué contenido útil puedo agregar en una Wiki?
Hola, Diego Mauricio. Una Wiki es el espacio ideal para documentación técnica estructurada que va más allá de un simple archivo. Puedes incluir:
Guías de inicio rápido: Pasos esenciales para que alguien nuevo use tu proyecto.
Índices de navegación: Estructuras que conectan diferentes secciones para facilitar la lectura.
Detalles del proyecto: Explicaciones profundas sobre la arquitectura o funcionalidades específicas.
Barra lateral personalizada (_Sidebar): Un menú persistente para que los usuarios siempre encuentren el camino de regreso a la página principal.
Piensa en la Wiki como el "manual de usuario" de tu software. Lo mejor es que puedes clonarla localmente para editarla cómodamente con tu editor Markdown favorito.
si no encuentran el botón de wiki probablemente lo tienen desactivas para activarlo ve a la configuración del repositorio en la parte donde dice features marca el botón que dice wiki
Hola que tal platzinautas!
Las wikis son una colaboración muy importante a la hora de hacer proyectos que necesitan una descripción mas elaborada, piensa a la hora de un proyecto, ¿sera necesario crear una wiki?
o mi archivo README.md es suficiente? esta herramienta te puede ayudar a dar mas información de una manera amigable y fácil de seguir (si le damos una buena estructura). Te recomiendo tomar un respiro, leer un poco de como usar las wikis y si te sientes de humor incluso puedes ver mas funcionalidades esta como dar accesos a la edicion de las wikis por los colaboradores, inhabilitar la wiki o incluso copiarla en tu repositorio local.
