From 569f51e85fd915fb2e176e7f8a1441deb753944e Mon Sep 17 00:00:00 2001 From: Anavelyz Date: Tue, 23 Aug 2022 00:59:28 -0400 Subject: [PATCH 1/4] Review articles 0023 and 0052 --- .../documentacioncodigoabierto.md | 24 +++++++++---------- pages/blog/0052-carpentries/carpentries.md | 14 +++++------ 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md b/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md index d4ef25be..17181743 100644 --- a/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md +++ b/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md @@ -1,5 +1,5 @@ -Independientemente del tipo de proyecto en el que participes o de su objetivo, la documentación es un factor muy importante a la hora de crear proyectos accesibles y inclusivos, en el sentido de que facilita muchísimo tanto su uso como la colaboración entre personas que no estén activamente involucradas en su desarrollo. Establecer de forma clara términos de uso del código, manuales o guías permite a tus usuarios ser autosuficientes y dar sugerencias mucho más útiles y profundas, además de que puede ser el factor clave entre que alguien se vuelva un colaborador o que termine ignorando tu proyecto. Tal como dice WriteTheDocs[2]: +Independientemente del tipo de proyecto en el que participes o de su objetivo, la documentación es un factor muy importante a la hora de crear proyectos accesibles e inclusivos, en el sentido que facilita en gran medida tanto su utilización como la colaboración entre personas que no estén activamente involucradas en su desarrollo. Establecer de forma clara términos de uso del código, manuales o guías permite a tus usuarios ser autosuficientes y dar sugerencias mucho más útiles y profundas, además de que puede ser el factor clave para que alguien se vuelva un colaborador o que termine ignorando tu proyecto. Tal como dice WriteTheDocs [2]: - Si la gente no sabe que tu proyecto existe, no lo usarán. -- Si la gente no sabe como instalar tu codigo, no lo usarán. -- Si la gente no puede entender como usar tu codigo, no lo usarán. +- Si la gente no sabe como instalar tu código, no lo usarán. +- Si la gente no puede entender como usar tu código, no lo usarán. -Fuera de cuestiones de colaboración o facilidad de lectura, es obvio también que el código se hace progresivamente más dificíl de entender y recordar conforme el proyecto avanza y se hace más extenso, por lo que la documentación se vuelve una herramienta de supervivencia, especialmente si no pretendes trabajar en el código con frecuencia. Algo que puede ocurrirte con más frecuencia que la que esperas, es estar en la situación donde quieres continuar un proyecto de hace meses pero no entiendes absolutamente nada de lo que hace el código. +Fuera de cuestiones de colaboración o facilidad de lectura, es obvio también que el código se hace progresivamente más difícil de entender y recordar conforme el proyecto avanza y se hace más extenso, por lo que la documentación se vuelve una herramienta de supervivencia, especialmente si no pretendes trabajar en el código con frecuencia. Algo que puede ocurrirte con más frecuencia de la que esperas, es estar en la situación donde quieres continuar un proyecto de hace meses, pero no entiendes absolutamente nada de lo que hace el código. -Por estas razones (¡y muchas otras!) la documentación de tu trabajo es imperativa. Sin embargo, normalmente durante el proceso de documentación, utilizamos destrezas que no suelen aprenderse en trabajos relacionados con software, por lo que los lineamientos que se deben seguir para llevar a cabo una buena documentación pueden no estar muy claros. Entonces, ¿qué es lo que hace una buena documentación de codigo abierto? +Por estas razones (¡y muchas otras!) la documentación de tu trabajo es imperativa. Sin embargo, es común que durante el proceso de documentación, utilicemos destrezas que no suelen aprenderse en trabajos relacionados con software, por lo que los lineamientos que se deben seguir para llevar a cabo una buena documentación pueden no estar muy claros. Entonces, ¿qué es lo que hace una buena documentación de código abierto? ## Accesibilidad -A la hora de escribir tu documentación, tienes que tener en cuenta que la van a leer tanto usuarios como desarrolladores, y que por lo general van a querer acceder a la información de la forma mas rápida y completa posible. El uso de hipervínculos y tablas de contenidos ayuda bastante, permitiéndote reutilizar otras documentaciones abiertas, a la vez que puedes mantener la información ordenada y concisa, ayudando a los usuarios encontrar los términos o datos que necesitan de la forma más rápida y sencilla posible. Por esta razón también es recomendado poner ciertos datos que van a buscar la mayoría de los interesados en un primer momento, tales como: la licencia que utilices, la meta del proyecto, ejemplos de uso, lista de tareas por realzar, etc. +A la hora de escribir tu documentación, tienes que tener en cuenta que la van a leer tanto usuarios como desarrolladores, y que por lo general van a querer acceder a la información de la forma más rápida y completa posible. El uso de hipervínculos y tablas de contenidos ayuda bastante, permitiéndote reutilizar otras documentaciones abiertas, a la vez que puedes mantener la información ordenada y concisa, ayudando a los usuarios encontrar los términos o datos que necesitan de la forma más rápida y sencilla posible. Por esta razón, también es recomendado poner ciertos datos que van a buscar la mayoría de los interesados en un primer momento, tales como: la licencia que utilices, la meta del proyecto, ejemplos de uso, lista de tareas por realizar, etc. ## Comunicación con tus usuarios -Puede sonar obvio, pero la documentación al final del dia, está pensada para que la lean tus usuarios. Si está dentro de la posibilidad, es bastante beneficioso agregar canales por los cuales puedan consultar y hasta contribuir otros desarrolladores: pull requests, tus cuentas en redes sociales, acceso al rastreamiento de problemas, FAQs, entre otros. Para este fín puedes usar ciertas convenciones como el archivo CONTRIBUTING.md, el cual especifica normas de conducta, como se prefiere que se comuniquen los usuarios, y las responsibilidades de los administradores del repositorio. +Puede sonar obvio, pero la documentación, al final del día, está pensada para que la lean tus usuarios. Si está dentro de la posibilidad, es bastante beneficioso agregar canales por los cuales puedan consultar y hasta contribuir otros desarrolladores: pull requests, tus cuentas en redes sociales, acceso al rastreamiento de problemas, FAQs, entre otros. Para este fin puedes usar ciertas convenciones como el archivo CONTRIBUTING.md, el cual especifica normas de conducta, como se prefiere que se comuniquen los usuarios, y las responsabilidades de los administradores del repositorio. -También podemos añadir que contribuir a la documentación de cualquier repositorio es una forma facil y relativamente sencilla de apoyar un proyecto sín involucrarse demasiado. Este es uno de los ámbitos donde cualquiera puede aportar perspectivas relevantes, sín importar demasiado su trasfondo o habilidades particulares. +También podemos añadir que contribuir a la documentación de cualquier repositorio es una forma fácil y relativamente sencilla de apoyar un proyecto, sin involucrarse demasiado. Este es uno de los ámbitos donde cualquiera puede aportar perspectivas relevantes, sin importar demasiado su trasfondo o habilidades particulares. ## Guías concisas y ejemplos sencillos -Sín importar el tipo de programa que estés desarollando, facilitará muchisimo su uso si das algunos ejemplos de cómo se utiliza en un contexto cotidiano con una guía paso a paso o una pequeña sección en su manual especificamente para principiantes, con algunos comandos y funciones relevantes para el uso mas basico de tu código. Te puede resultar útil el uso de capturas de pantallas, incluir configuración de texto inteligente (con bloques de codigo, resaltamiento de sintaxis, etcetera), acompañados de parrafos de texto concisos, escritos con lenguaje simple y sin entrar mucho en terminología especifica. +Sín importar el tipo de programa que estés desarrollando, facilitará bastante su uso si das algunos ejemplos de cómo se utiliza en un contexto cotidiano, con una guía paso a paso o una pequeña sección en su manual específicamente para principiantes, con algunos comandos y funciones cruciales para el uso más básico de tu código. Te puede resultar útil el empleo de capturas de pantallas, incluir configuración de texto inteligente (con bloques de código, resaltamiento de sintaxis, etcétera), acompañados de párrafos de texto concisos, escritos con lenguaje simple y sin entrar mucho en terminología específica. -Siempre recomendamos que si necesitas ayuda en cuanto a como escribir documentación, ¡sólo hace falta revisar lo que ya han escrito otros! Ya sea para aprender ciertos modos de escritura que son comunes dentro de esta practica, para aprender de los errores que cometen los demás, o simplemente para situarte en el lugar de alguien que este revisando tu código por primera vez. Leer lo que han escrito los demas con el enfoque de aprender es una buena estrategia. Prácticamente todas las distribuciones de Linux incluyen el comando `man` que te permite ver información sobre varios comandos de bash, y muchos repositorios de Github tienen por lo menos un archivo `README.md`, visto en cuanto entras a su pagina, cuyo objetivo es mostrar el principal propósito y uso del proyecto. Es solo cuestión de revisar un poco para encontrar una enorme variedad de ejemplos. +Siempre recomendamos que si necesitas ayuda en cuanto a cómo escribir documentación, ¡solo hace falta revisar lo que ya han escrito otros! Ya sea para aprender ciertos modos de escritura que son comunes dentro de esta práctica, para aprender de los errores que cometen los demás, o simplemente para situarte en el lugar de alguien que esté chequeando tu código por primera vez. Leer lo que han escrito los demás con el enfoque de aprender es una buena estrategia. Prácticamente, todas las distribuciones de Linux incluyen el comando `man` que te permite ver información sobre varios comandos de bash, y muchos repositorios de Github tienen por lo menos un archivo `README.md`, visto en cuanto entras a su página, cuyo objetivo es mostrar el principal propósito y uso del proyecto. Es solo cuestión de revisar un poco para encontrar una enorme variedad de ejemplos. [1]: https://opensourcesurvey.org/2017/ "Open Source Survey" [2]: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#why-write-docs "Write The Docs | Why Write Docs?" diff --git a/pages/blog/0052-carpentries/carpentries.md b/pages/blog/0052-carpentries/carpentries.md index 9e71cd08..977684bd 100644 --- a/pages/blog/0052-carpentries/carpentries.md +++ b/pages/blog/0052-carpentries/carpentries.md @@ -14,27 +14,27 @@ ![header](../../../images/blog/por-que-deberias-considerar-carpentries-como-una-referencia-para-aprender-ciencia-de-datos/header.png) -Cuando estamos por aprender y comprender al máximo sobre algo en especifico es vital que tengamos fuentes de información que nos hagan este proceso más sencillo, y que ante cualquier duda que tengamos la ayuda sea oportuna. +Cuando estamos por aprender y comprender al máximo sobre algo en específico, es vital que tengamos fuentes de información que nos hagan este proceso más sencillo, y que ante cualquier duda que tengamos la ayuda sea oportuna. "The Carpentries es un proyecto que engloba las comunidades de instructores, capacitadores, mantenedores, ayudantes y simpatizantes de Software Carpentry, Data Carpentry, y Library Carpentry que comparten la misión de enseñar habilidades básicas de computación y ciencia de datos a los investigadores." (https://carpentries.org/about/) -Este proyecto es ideal para aprender ciencia de datos porque brinda una serie de materiales diseñados para ello. Hay dos modalidades de enseñanza, una que comprende talleres y otra en formato semestral. Los planes de estudio que ofrece The carpentries varia de acuerdo a las tres comunidades que engloba. Esto es porque cada una se centra en un aspecto práctico orientado a la necesidad del investigador. Para conocer un poco mejor acerca de ello veamos las siguientes descripciones, +Este proyecto es ideal para aprender ciencia de datos porque brinda una serie de materiales diseñados para ello. Hay dos modalidades de enseñanza, una que comprende talleres y otra en formato semestral. Los planes de estudio que ofrece The carpentries varía de acuerdo a las tres comunidades que engloba. Esto es porque cada una se centra en un aspecto práctico orientado a la necesidad del investigador. Para conocer un poco mejor acerca de ello veamos las siguientes descripciones, - Data Carpentry, facilita y desarrolla lecciones para talleres orientados a un área de estudio específico, de modo que se enseña a los investigadores las habilidades más relevantes para su dominio; utilizando ejemplos de su tipo de trabajo. Por lo tanto, por esta comunidad podemos encontrar varios tipos de talleres y planes de estudios organizados por dominio. Actualmente, los dominios son: ecología, biología, genómica, Ciencias Sociales y datos geoespaciales. Descripción extraída de: https://datacarpentry.org/lessons/ - Software Carpentry tiene como objetivo ayudar a los investigadores a ser más capaces de escribir software para aplicaciones de investigación. Esto significa centrarse en los lenguajes de programación, entornos de scripting y aplicar el control de versiones para gestionar el código. - Los talleres de Software Carpentry utilizan una pedagogía de tipo práctico para ayudar a los investigadores a crear confianza y capacidad en el UNIX Shell (BASH), Python o R y el software de control de versiones Git. Opcionalmente posee módulos para pruebas de unidades y SQL. + Los talleres de Software Carpentry emplean una pedagogía de tipo práctico para ayudar a los investigadores a crear confianza y capacidad en el UNIX Shell (BASH), Python o R y el software de control de versiones Git. Opcionalmente, posee módulos para pruebas de unidades y SQL. Software Carpentry es una manera de empezar a construir algunas habilidades y destrezas computacionales en una comunidad de investigación. Las habilidades prácticas y los métodos con los que se enseñan resultan ser útiles para otras enseñanzas avanzadas de seguimiento. Para ver esta descripción y otros aspectos fundamentales visita https://software-carpentry.org/lessons/ o https://cookbook.carpentries.org/the-carpentries.html#software-carpentry -- Library Carpentry, posee un plan de estudios básico que actualmente consiste en nueve lecciones. Estas han sido enseñadas muchas veces, y han sido refinadas después de la retroalimentación del instructor y del estudiante. Las lecciones introducen términos, frases y conceptos en el desarrollo de software y la ciencia de datos, cómo trabajar mejor con las estructuras de datos y cómo utilizar expresiones regulares para encontrar y comparar datos. Presenta la interfaz de línea de comandos de estilo Unix, y enseña la navegación básica en el shell, así como el uso de bucles y tuberías para vincular los comandos del shell. También introduce el grep para buscar y subconjuntar datos entre archivos. Los ejercicios cubren el conteo y la extracción de datos. Además, cubre el trabajo con OpenRefine para transformar y limpiar datos, y los beneficios de trabajar en colaboración a través de Git/GitHub y el uso del control de versiones para realizar un seguimiento de su trabajo. Para encontrar esta descripción y más información visita: https://librarycarpentry.org/lessons/ +- Library Carpentry, posee un plan de estudios básico que actualmente consiste en nueve lecciones. Estas han sido enseñadas muchas veces, y han sido refinadas después de la retroalimentación del instructor y del estudiante. Las lecciones introducen términos, frases y conceptos en el desarrollo de software y la ciencia de datos, cómo trabajar mejor con las estructuras de datos y cómo utilizar expresiones regulares para encontrar y comparar datos. Presenta la interfaz de línea de comandos de estilo Unix, y enseña la navegación básica en el shell, así como el uso de bucles y tuberías para vincular los comandos del shell. También introduce el grep para buscar y unir grupos de datos entre archivos. Los ejercicios cubren el conteo y la extracción de datos. Además, cubre el trabajo con OpenRefine para transformar y limpiar datos, y los beneficios de trabajar en colaboración a través de Git/GitHub y la utilización del control de versiones para realizar un seguimiento de su trabajo. Para encontrar esta descripción y más información, visita: https://librarycarpentry.org/lessons/ Con estas descripciones se hace notar el empeño de estas comunidades por lograr que los investigadores tengan las herramientas necesarias a la hora de implementar análisis de datos y otros elementos importantes en sus investigaciones. Lo mejor de esto es que van desde lo más básico hasta lo que se considera pertinente para que el conocimiento quedé plasmado en cada estudiante. -También, es importante mencionar que todas las lecciones se distribuyen bajo la licencia CC-BY y son libres para su reutilización o adaptación, con atribución. Esto ha generado que la personas las utilicen en lecciones, en cursos, para construir nuevas lecciones o para el aprendizaje autoguiado. +También, es valioso mencionar que todas las lecciones se distribuyen bajo la licencia CC-BY y son libres para su reutilización o adaptación, con atribución. Esto ha generado que las personas las utilicen en lecciones, en cursos, para construir nuevas lecciones o para el aprendizaje autoguiado. -Ahora, entorno a todo lo anterior se tiene que +Ahora, en torno a todo lo anterior, se tiene que - Existe una o varias comunidades que respaldan este proyecto y las lecciones que han desarrollado. @@ -42,7 +42,7 @@ Ahora, entorno a todo lo anterior se tiene que - El acceso a los materiales desarrollados por el proyecto puede hacerse mediante websites. https://librarycarpentry.org/lessons, https://datacarpentry.org/lessons/, https://software-carpentry.org/lessons/, (https://carpentries.org/workshops-curricula/). -- Las lecciones están bien estructuradas. En el caso de Data Carpentry se encuentran clasificadas según un dominio y, a pesar de esto los conocimientos impartidos también se pueden aplicar a otras area. Mientras que Software Carpentry y Library Carpentry son ideales para aprender elementos de la programación haciendo uso de bibliotecas y otras herramientas vitales en el análisis de datos. +- Las lecciones están bien estructuradas. En el caso de Data Carpentry se encuentran clasificadas según un dominio y, a pesar de esto, los conocimientos impartidos también se pueden aplicar a otras áreas. Mientras que Software Carpentry y Library Carpentry son ideales para aprender elementos de la programación haciendo uso de bibliotecas y otras herramientas vitales en el análisis de datos. - Puedes tener acceso a contenidos nuevos con el trascurso del tiempo. From 9470df05786aa5951f7351b2f4fae765f8163f9e Mon Sep 17 00:00:00 2001 From: EverVino Date: Wed, 24 Aug 2022 20:25:38 -0400 Subject: [PATCH 2/4] Aumentando tags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Añadiendo tags a sugerencia de Anavelyz --- pages/blog/0052-carpentries/carpentries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/blog/0052-carpentries/carpentries.md b/pages/blog/0052-carpentries/carpentries.md index 977684bd..23ad914f 100644 --- a/pages/blog/0052-carpentries/carpentries.md +++ b/pages/blog/0052-carpentries/carpentries.md @@ -3,7 +3,7 @@ .. slug: por-que-deberias-considerar-carpentries-como-una-referencia-para-aprender-ciencia-de-datos .. date: 2021-03-08 .. author: Anavelyz Pérez -.. tags: data science, learning +.. tags: data science, learning, carpentries, ciencia de datos .. category: learning .. link: .. description: From d3f77fb918e707021a900e5166defc752c159b1b Mon Sep 17 00:00:00 2001 From: Anavelyz Date: Sun, 28 Aug 2022 22:31:39 -0400 Subject: [PATCH 3/4] Adding suggestions by Ever --- .../documentacioncodigoabierto.md | 8 ++++---- pages/blog/0052-carpentries/carpentries.md | 3 ++- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md b/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md index 17181743..fba64b19 100644 --- a/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md +++ b/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md @@ -15,11 +15,11 @@ ![header](../../../images/blog/si-ya-usas-codigo-abierto-te-contamos-como-puedes-sacarle-mayor-provecho-tu-documentacion-para-tus-articulos-y-publicaciones/header.png) -Con mucha frecuencia, los proyectos de código abierto suelen prestar poca atención al tema de documentación. De hecho, es tan común que la encuesta Open Source Survey [1] (realizada por Github, involucrando tanto académicos, como a trabajadores en la industria de computación, como colaboradores independientes) reportó que al menos 93% de los encuestados, creían que la documentación incompleta o sin actualizar era uno de los problemas más agravantes dentro de la esfera del software libre. En la misma encuesta, 60% de los participantes admitían también contribuir a la documentación de sus proyectos con muy poca frecuencia. +Con mucha frecuencia, los proyectos de código abierto suelen prestar poca atención al tema de documentación. De hecho, es tan común que la encuesta [Open Source Survey](https://opensourcesurvey.org/2017/) [1] (realizada por Github, involucrando tanto académicos, como a trabajadores en la industria de computación, como colaboradores independientes) reportó que al menos 93% de los encuestados, creían que la documentación incompleta o sin actualizar era uno de los problemas más agravantes dentro de la esfera del software libre. En la misma encuesta, 60% de los participantes admitían también contribuir a la documentación de sus proyectos con muy poca frecuencia. -Independientemente del tipo de proyecto en el que participes o de su objetivo, la documentación es un factor muy importante a la hora de crear proyectos accesibles e inclusivos, en el sentido que facilita en gran medida tanto su utilización como la colaboración entre personas que no estén activamente involucradas en su desarrollo. Establecer de forma clara términos de uso del código, manuales o guías permite a tus usuarios ser autosuficientes y dar sugerencias mucho más útiles y profundas, además de que puede ser el factor clave para que alguien se vuelva un colaborador o que termine ignorando tu proyecto. Tal como dice WriteTheDocs [2]: +Independientemente del tipo de proyecto en el que participes o de su objetivo, la documentación es un factor muy importante a la hora de crear proyectos accesibles e inclusivos, en el sentido que facilita en gran medida tanto su utilización como la colaboración entre personas que no estén activamente involucradas en su desarrollo. Establecer de forma clara términos de uso del código, manuales o guías permite a tus usuarios ser autosuficientes y dar sugerencias mucho más útiles y profundas, además de que puede ser el factor clave para que alguien se vuelva un colaborador o que termine ignorando tu proyecto. Tal como dice [Write The Docs | Why Write Docs?](http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#why-write-docs) [2]: - Si la gente no sabe que tu proyecto existe, no lo usarán. - Si la gente no sabe como instalar tu código, no lo usarán. @@ -45,5 +45,5 @@ Sín importar el tipo de programa que estés desarrollando, facilitará bastant Siempre recomendamos que si necesitas ayuda en cuanto a cómo escribir documentación, ¡solo hace falta revisar lo que ya han escrito otros! Ya sea para aprender ciertos modos de escritura que son comunes dentro de esta práctica, para aprender de los errores que cometen los demás, o simplemente para situarte en el lugar de alguien que esté chequeando tu código por primera vez. Leer lo que han escrito los demás con el enfoque de aprender es una buena estrategia. Prácticamente, todas las distribuciones de Linux incluyen el comando `man` que te permite ver información sobre varios comandos de bash, y muchos repositorios de Github tienen por lo menos un archivo `README.md`, visto en cuanto entras a su página, cuyo objetivo es mostrar el principal propósito y uso del proyecto. Es solo cuestión de revisar un poco para encontrar una enorme variedad de ejemplos. -[1]: https://opensourcesurvey.org/2017/ "Open Source Survey" -[2]: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#why-write-docs "Write The Docs | Why Write Docs?" +[1]: [Open Source Survey](https://opensourcesurvey.org/2017/) +[2]: [Write The Docs | Why Write Docs](http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#why-write-docs) \ No newline at end of file diff --git a/pages/blog/0052-carpentries/carpentries.md b/pages/blog/0052-carpentries/carpentries.md index 23ad914f..4c7c082f 100644 --- a/pages/blog/0052-carpentries/carpentries.md +++ b/pages/blog/0052-carpentries/carpentries.md @@ -40,7 +40,8 @@ Ahora, en torno a todo lo anterior, se tiene que - El contenido de sus lecciones están disponibles en la web bajo un formato que da la facilidad para reutilizar su contenido. -- El acceso a los materiales desarrollados por el proyecto puede hacerse mediante websites. https://librarycarpentry.org/lessons, https://datacarpentry.org/lessons/, https://software-carpentry.org/lessons/, (https://carpentries.org/workshops-curricula/). +- El acceso a los materiales desarrollados por el proyecto puede hacerse mediante sus websites. +En **Library Carpentry** los encontramos en la sección [*OUR LESSONS*](https://librarycarpentry.org/lessons), en el caso de **Data Carpentry**, en [*LESSONS*](https://datacarpentry.org/lessons/); para **Software Carpentry** también existe una sección [*LESSONS*](https://software-carpentry.org/lessons/). De manera general y resumida podemos conseguir los planes de estudio de Carpentries en la sección [*LEARN/OUR CURRICULA*](https://carpentries.org/workshops-curricula/). - Las lecciones están bien estructuradas. En el caso de Data Carpentry se encuentran clasificadas según un dominio y, a pesar de esto, los conocimientos impartidos también se pueden aplicar a otras áreas. Mientras que Software Carpentry y Library Carpentry son ideales para aprender elementos de la programación haciendo uso de bibliotecas y otras herramientas vitales en el análisis de datos. From 1e5dda1e162bce5c28d0990f884feef4527c12ae Mon Sep 17 00:00:00 2001 From: EverVino Date: Sun, 4 Sep 2022 19:13:43 -0400 Subject: [PATCH 4/4] Update documentacioncodigoabierto.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Poniendo un título a referencias --- .../documentacioncodigoabierto.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md b/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md index fba64b19..f7f0b2f7 100644 --- a/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md +++ b/pages/blog/0023-documentacioncodigoabierto/documentacioncodigoabierto.md @@ -15,11 +15,11 @@ ![header](../../../images/blog/si-ya-usas-codigo-abierto-te-contamos-como-puedes-sacarle-mayor-provecho-tu-documentacion-para-tus-articulos-y-publicaciones/header.png) -Con mucha frecuencia, los proyectos de código abierto suelen prestar poca atención al tema de documentación. De hecho, es tan común que la encuesta [Open Source Survey](https://opensourcesurvey.org/2017/) [1] (realizada por Github, involucrando tanto académicos, como a trabajadores en la industria de computación, como colaboradores independientes) reportó que al menos 93% de los encuestados, creían que la documentación incompleta o sin actualizar era uno de los problemas más agravantes dentro de la esfera del software libre. En la misma encuesta, 60% de los participantes admitían también contribuir a la documentación de sus proyectos con muy poca frecuencia. +Con mucha frecuencia, los proyectos de código abierto suelen prestar poca atención al tema de documentación. De hecho, es tan común que la encuesta [Open Source Survey](https://opensourcesurvey.org/2017/) (realizada por Github, involucrando tanto académicos, como a trabajadores en la industria de computación, como colaboradores independientes) reportó que al menos 93% de los encuestados, creían que la documentación incompleta o sin actualizar era uno de los problemas más agravantes dentro de la esfera del software libre. En la misma encuesta, 60% de los participantes admitían también contribuir a la documentación de sus proyectos con muy poca frecuencia. -Independientemente del tipo de proyecto en el que participes o de su objetivo, la documentación es un factor muy importante a la hora de crear proyectos accesibles e inclusivos, en el sentido que facilita en gran medida tanto su utilización como la colaboración entre personas que no estén activamente involucradas en su desarrollo. Establecer de forma clara términos de uso del código, manuales o guías permite a tus usuarios ser autosuficientes y dar sugerencias mucho más útiles y profundas, además de que puede ser el factor clave para que alguien se vuelva un colaborador o que termine ignorando tu proyecto. Tal como dice [Write The Docs | Why Write Docs?](http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#why-write-docs) [2]: +Independientemente del tipo de proyecto en el que participes o de su objetivo, la documentación es un factor muy importante a la hora de crear proyectos accesibles e inclusivos, en el sentido que facilita en gran medida tanto su utilización como la colaboración entre personas que no estén activamente involucradas en su desarrollo. Establecer de forma clara términos de uso del código, manuales o guías permite a tus usuarios ser autosuficientes y dar sugerencias mucho más útiles y profundas, además de que puede ser el factor clave para que alguien se vuelva un colaborador o que termine ignorando tu proyecto. Tal como dice [Write The Docs | Why Write Docs?](http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#why-write-docs): - Si la gente no sabe que tu proyecto existe, no lo usarán. - Si la gente no sabe como instalar tu código, no lo usarán. @@ -45,5 +45,8 @@ Sín importar el tipo de programa que estés desarrollando, facilitará bastant Siempre recomendamos que si necesitas ayuda en cuanto a cómo escribir documentación, ¡solo hace falta revisar lo que ya han escrito otros! Ya sea para aprender ciertos modos de escritura que son comunes dentro de esta práctica, para aprender de los errores que cometen los demás, o simplemente para situarte en el lugar de alguien que esté chequeando tu código por primera vez. Leer lo que han escrito los demás con el enfoque de aprender es una buena estrategia. Prácticamente, todas las distribuciones de Linux incluyen el comando `man` que te permite ver información sobre varios comandos de bash, y muchos repositorios de Github tienen por lo menos un archivo `README.md`, visto en cuanto entras a su página, cuyo objetivo es mostrar el principal propósito y uso del proyecto. Es solo cuestión de revisar un poco para encontrar una enorme variedad de ejemplos. -[1]: [Open Source Survey](https://opensourcesurvey.org/2017/) -[2]: [Write The Docs | Why Write Docs](http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#why-write-docs) \ No newline at end of file +## Referencias + +- [Open Source Survey](https://opensourcesurvey.org/2017/) + +- [Write The Docs | Why Write Docs](http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#why-write-docs)