Gracias por compartir tu experiencia y tus ideas con la comunidad de desarrolladores.
Nuestra publicación te ayudará a enseñar e inspirar a desarrolladores, diseñadores y científicos de datos de todo el mundo.
Como uno de los sitios de tecnología más visitados en la web, freeCodeCamp.org puede ayudarte a llegar a miles de personas que se beneficiarán de tu sabiduría.
Nuestra organización sin fines de lucro también tiene una gran presencia en las redes sociales, una fuerte accesibilidad, SEO y una reputación establecida como un recurso de aprendizaje serio. Todos estos se traducirán en más lectores para tus artículos.
En esta guía de estilo, te daremos consejos sobre cómo puedes maximizar tu impacto haciendo que tus artículos sean lo más fuertes posible.
Este no es un lugar para desafíos de estilo "blog-a-día" o publicaciones de observación de flujo de conciencia.
Trae tus hechos. Trae tus citas. Trae tus fragmentos de código. Traiga tus visualizaciones de datos.
Años de datos muestran que cuanto más profundo sea un artículo, más tiempo pasarán las personas leyéndolo y es más probable que lo compartan con sus amigos.
Si no puede escribir al menos 1,000 palabras sobre tu tema, intenta investigarlo primero.
Al sumergirse más profundamente y expandir tu investigación, podrás ofrecer más información a tus lectores.
La gente está ocupada. Así que hay que captar su atención de inmediato. ¿Cómo se hace eso? Con un título convincente.
Titulares: La única parte de tu artículo que 100% de la gente va a leer
Antes de comenzar a escribir tu historia, dediqua tiempo a elaborar un titular convincente. Todo tu artículo surgirá de ese titular y volverás a conectarlo para apoyarlo.
Hemos encontrado dos arquetipos que funcionan bien: artículos técnicos profundos y narrativas personales.
Aquí hay algunas estructuras de titulares que hemos encontrado que funcionan bien para artículos técnicos profundos:
- Cómo solucionar…"
- Cómo construir…"
- “Cómo [tarea] con [herramienta]”
- "Cómo [algo] funciona"
- "La guía [adjetiva] para…"
- “¿Qué es un [sustantivo]? En español, por favor.”
- “¿Qué es exactamente [sustantivo]?”
- “Por qué [algo] importa.”
- "Aprender [algo] en N horas”
- "Una historia de [algo]”
- "La historia detrás [algo]”
Y aquí hay algunas estructuras de titulares que funcionan bien para narrativas personales:
- "Cómo [hice algo]"
- “Yo [hice algo]. Esto es lo que aprendí.”
- "Cómo pasé de [algo] a [algo] en N años”
- "Por qué empecé [algo]”
- "Nunca volveré a [algo] otra vez. He aquí por qué.”
- “Cómo [hice algo] sin [algo]”
- "¿Por qué ya no [algo]"
Agrega tus Imágenes de Portada
Una vez que hayas elegido tu titular claro e informativo, agrega una bonita imagen de portada. Haz clic en el engranaje en la esquina superior derecha.
Algunos colaboradores crean su propia portada para su artículo. Un sitio gratuito como Canva.com puede ayudarte con este proceso. (Si deseas evitar que los bordes de tus imágenes se corten cuando tu artículo se comparte en Facebook o Twitter, usa una relación de aspecto de la imagen de 1.91:1.)
Si no tienes una imagen, puedes agregar una imagen Creative Commons Zero (sin atribución necesaria) haciendo clic en el botón Unsplash en la esquina inferior izquierda.
Establecer tu URL de publicación
Puedes establecer la URL de tu artículo directamente. Recomendamos mantener estos cortos y descriptivos como "aprendizaje-de-máquina-con-pytorch-tutorial" o "de-retail-worker-a-software-developer".
Elige tus etiquetas
Puedes elegir de una a cinco etiquetas para tu artículo. Una vez que los hayas elegido, simplemente avísale al equipo editorial y los agregaremos por ti.
Estas etiquetas facilitarán a los lectores descubrir tus artículos a través de la búsqueda y al navegar por las etiquetas.
La primera etiqueta que elijas es la más importante, y se mostrará encima de tu artículo, así:
Por favor, no cambies ninguna de las metainformación en el menú. Nuestra publicación tiene valores predeterminados sensatos para estos.
Consejos para escribir un artículo que la gente realmente leerá
La gramática, la ortografía y el formato sí importan
Es más fácil leer artículos claros y con el formato adecuado. Aquí hay algunos consejos para que tus artículos sean lo más legibles posible:
- Que sea sencillo. Utiliza un lenguaje sencillo y directo siempre que sea posible.
- Usa oraciones cortas. Divida oraciones más largas en oraciones más cortas. Esto ayuda a las personas a leer más rápido y entender mejor.
- Usa párrafos cortos. Divide los párrafos más largos en uno o dos párrafos de oraciones. Las paredes de texto harán que tus lectores abandonen tu artículo o solo le den un vistazo rapido.
- Limpiar la puntuación. ¡Demasiados signos de exclamación pueden distraer!!! Semi-dos puntos rara vez son necesarios; sólo tienes que utilizar un punto en su lugar. Y las elipses son... bien... generalmente un poco mucho.
- Utiliza subtítulos para estructurar el texto. Nuestra publicación te ofrece tamaños de encabezado grandes y pequeños para tu kit de herramientas. Utiliza encabezados grandes para los temas principales y subencabezados más pequeños para las secciones dentro de esos temas.
- No uses negrita excesiva, cursiva o ambas cosas. Demasiado formato de texto hace que sea difícil de leer. Especialmente si usa negrita y cursiva juntas. Use negrita y cursiva por separado, y con moderación.
- Elimina abreviaturas. Hacen que los artículos sean más difíciles de entender. Deletrea cualquier acrónimo que no es bien conocido. Convierte expresiones latinas como “e.g.” en “por ejemplo” y “… etc.” en “como ...”
Prueba leyendo tu artículo. Y después, revisa de nuevo.
Algunos colaboradores escriben rápidamente para que puedan obtener sus ideas en papel. Otros colaboradores hacen toda su investigación antes de escribir una sola palabra.
Sea cual sea tu proceso de escritura, asegúrete de alejarte de tu artículo y volver con un nuevo par de ojos.
Lee tu artículo otra vez. Luego léelo en voz alta. Te sorprenderán los pequeños errores, errores ortográficos y frases incómodas que capturas.
Agrega resaltado de sintaxis a tu código
Puedes crear un bloque de código escribiendo tres backticks (```), seguido de golpear la barra espaciadora.
Incluso puedes especificar el lenguaje de programación para el que desees resaltar la sintaxis..
Por ejemplo, escribiendo ```js te dará resaltado de sintaxis de JavaScript. Y también admitimos el resaltado de sintaxis para una docena de otros lenguajes de programación populares.
Manténte en el tema
El tiempo de tus lectores es finito. Ayuda a tus lectores a obtener el mayor valor posible de tus artículos antes de que tengan que seguir adelante con sus vidas.
Manten tus artículos técnicos profundos lo más paso a paso posible
- Escribe una introducción concisa que le diga a los lectores lo que van a lograr.
- Usa una lista numerada como esta para indicar los pasos.
- Empaca con tantos detalles como puedas.
- Cierra recordando a los lectores lo que acaban de lograr.
Cuenta tus historias personales como una novela
Aunque tu titular probablemente regalará el final de tu historia ("Cómo pasé de un camionero nocturno a un desarrollador de software en 2 años"), todavía puedes contarlo como una novela.
En lugar de saltar a través del tiempo, comienza desde el principio y pinta una imagen de tu vida antes y después de tu viaje.
Vee si puedes enmarcar tu historia en torno a un conflicto central. Por ejemplo, superando:
- desafíos de inmigración
- entrevistas brutales de trabajo
- discapacidades de aprendizaje
- discriminación de edad
- o simplemente la dilación (el desafío más común)
El conflicto es fundamental para la narrativa. Los libros y las películas son interesantes debido al conflicto entre los personajes, su entorno e incluso dentro de sí mismos.
Escribir artículos completos más largos en lugar de artículos de varias partes
Hemos observado una y otra vez que las personas no se molestarán en leer la segunda, tercera o enésima parte de una serie si no han leído todas las partes anteriores.
Al mismo tiempo, hemos visto que los artículos muy largos y en profundidad funcionan sorprendentemente bien. La gente marcará tu artículo o lo compartirá en las redes sociales para que puedan volver a él.
Cuando la gente ve que un artículo es largo, a menudo asumen que el artículo es serio y completo. Esto inspira a la gente a reducir la velocidad y realmente pasar tiempo leyendo tu artículo. Muchas personas incluso abrirán su editor de código y código en casa.
Manténlo clasificado G como sea posible
La comunidad freeCodeCamp es en su mayoría son adultos, pero hay algunos niños aquí también.
Si estás escribiendo sobre un tema como el acoso sexual, no hay una manera real de mantenerlo clasificado "G". Pero en la mayoría de las circunstancias, esto es posible.
Trata de no usar blasfemias a menos que esté en una cita directa, y manténte alejado de los memes potencialmente ofensivos.
Finalmente, si un artículo parece violar el código de conducta de freeCodeCamp, lo eliminaremos inmediatamente. Pero guardaremos una copia de la misma y te la enviaremos para tus propios registros, para que no pierdas tu trabajo.
Utiliza Creative Commons Cero imágenes o imágenes que creaste tu mismo
Puedes incluir capturas de pantalla y otras imágenes que hayas creado tu mismo. Pero si no posees los derechos de una foto, usa una imagen similar que sea Creative Commons Zero en su lugar. Estos no requieren tarifas de licencia o atribución.
El editor de artículos de nuestra publicación tiene una herramienta Unsplash incorporada. Puedes presionar enter para crear un nuevo párrafo, luego haz clic en el signo más en el lateral y elija "Unsplash".
Algunas imágenes, como los webcomics, se crean pensando en compartir. Para estos, puedes insertar la imagen y luego decir "Crédito de la imagen: XKCD" con un enlace a la página específica para el webcomic.
Siempre acredita tus fuentes
El plagio es cuando alguien malinterpreta la escritura de otra persona como propia. Es un delito grave que hace que las personas sean despedidas de trabajos y expulsadas de escuelas. Y lo tomamos igual de en serio en la publicación de freeCodeCamp.
Pocas personas han sido lo suficientemente descaradas como para intentar plagio en la publicación de freeCodeCamp. Pero ha habido algunos de ellos en los últimos 6 años. Los hemos atrapado, eliminado sus artículos y los hemos prohibido de nuestra comunidad de por vida.
No te preocupes, no vas a plagiar accidentalmente nada. El plagio es un acto intencional.
Si estás parafraseando (o citando directamente) algo que alguien dijo en otro artículo, video, curso u otro medio, debes acreditarlos.
Si tu código está fuertemente inspirado en (o tomado prestado de) el código de otra persona, debes acreditarlo.
Antes de publicar un artículo que se apoya fuertemente en el trabajo de otra persona, pregúntate: ¿mi artículo se expande sustancialmente en el trabajo de esa persona? Si no, puede que no garantice un artículo.
Siempre atribuye citas a las personas que originalmente las dijeron. Si se trata de una cita de varias líneas, puede usar comillas de extracción como estas para dividir párrafos más largos:
“Cuando tienes ingenio propio, es un placer dar crédito a otras personas por las suyas.”
― Criss Jami
Sin publicación cruzada, por favor.
La publicación cruzada es ineficaz. Si deseas que mucha gente lea tu artículo, simplemente centra tus esfuerzos en una sola publicación, ya sea la publicación de freeCodeCamp, tu propio blog o una revista en línea.
Sin embargo, puedes tomar algunas de tus publicaciones de blog personales sobre un tema similar (como "Complementos de Visual Studios" o "Comandos avanzados de Bash") y antologizarlas en un único artículo de freeCodeCamp más largo.
Maneras aceptables que tu puedes auto-promocionarse en sus artículos
freeCodeCamp.org es una organización sin fines de lucro apoyada por donantes. No queremos que nadie tenga la impresión de que hacemos "colocación pagada" (no), ya que esto podría desalentar a las personas de donarnos.
Al mismo tiempo, entendemos totalmente que es posible que desees dar a conocer su último libro, curso, aplicación SaaS u otro producto.
Te pedimos que mantengas esto tan buen gusto como sea posible. Está perfectamente bien tener una llamada a la acción de una frase para su producto al final de tu artículo.
No abras tu artículo con un enlace a su producto, ya que parece spam.
También ten en cuenta que no permitimos cuentas de marca. Prohibimos cualquier tipo de escritura fantasma. Y no transferiremos artículos de un empleado a otro.
Y por favor, no escriba historias en nombre de otras personas que aún no han ganado su cuenta de colaborador.
Ten en cuenta que para tus propios propósitos de SEO, a diferencia de la mayoría de los sitios web populares, todos los enlaces de nuestra publicación son rel="doFollow". Esto significa que sí, cada página a la que vincules (incluido tu propio blog) recibirá un impulso en el ranking de Google. Por favor, ten esto en cuenta y no exageres.
Terminando el proceso
Una vez que estés seguro de que tu historia está lista para los lectores, envía un enlace a tu borrador al editores@freecodecamp.org. Nuestro equipo editorial revisará rápidamente y realizará ediciones para fortalecer aún más tu artículo antes de publicarlo.
Las principales cosas que nos importan son el titular y los párrafos iniciales. Si notamos algún problema de formato de texto o errores gramaticales, los corregiremos también.
Si todavía creemos que tu artículo necesita un trabajo significativo, te lo diremos, y luego puedes volver a enviarlo una vez que hayas realizado esos cambios.
Otros consejos útiles
GitHub Markdown
¿Sabías que puedes usar Markdown como se usa en GitHub para componer tus artículos?
Puedes pegar markdown en espanol/news y se convertirá instantáneamente en texto enriquecido.
También puedes escribir la sintaxis de markdown al principio de una línea, digamos # o ## para encabezados, o * para una lista con viñetas, luego comienza a escribir. El texto cambiará al formato especificado.
Ve fácil en las incrustaciones
Puedes incrustar cosas como tweets y videos de YouTube si lo deseas. Simplemente haga clic en el icono + al comienzo de una nueva línea, y puedes elegir entre una variedad de herramientas de incrustación.
Dicho esto, le animamos a utilizar estos con moderación, por tres razones:
- Las incrustaciones realizan una llamada a un servicio externo, como Twitter, lo que puede ralentizar la experiencia
- Muchas personas que leen la publicación lo están haciendo usando lectores de pantalla. Una gran parte de la comunidad de desarrolladores vive con impedimentos visuales (o completamente ceguera). Los incrustados son menos accesibles que el texto.
- Cada artículo de publicación tiene una versión de Accelerated Mobile Pages y es posible que las incrustaciones no se muestren correctamente allí.
Si aún no tienes una cuenta de colaborador, puedes solicitar una aquí.
Gracias por compartir tus ideas con la comunidad de desarrolladores.
Esperamos que esta guía te ayude a escribir mejores artículos para que toda la comunidad pueda beneficiarse de tu visión.
Feliz programación!
— El equipo editorial freeCodeCamp
Traducido del artículo - The freeCodeCamp Publication Style Guide