Outline an engaging document
Before writing a single line of code.
🇪🇸 Este post está escrito en inglés y español. Puedes encontrar el texto en español más abajo.
🇺🇸 Are you ready to challenge yourself?
Let’s get started with the basics. Here, you can learn how to create a document based on existing templates and how to build an engaging document from the beginning.
Install {pagedown} package 📦
The first step is to make sure that you’ve installed {pagedown} in your machine. If you haven’t, then run this line of code in your console:
install.packages("pagedown")Start with a boring template
Once you install the 📦, you’ll have access to a series of templates. The thesis_paged template is an excellent starting point if you want to write a fully reproducible thesis or dissertation:
These days, I often create internal and external reports based on the html_paged template, which is the most generic template in the 📦:
Regardless of the template you choose, as you save the template somewhere on your computer, remember that this document will be one of many pieces in your workflow. You need to keep in mind that the document needs to access folders with data, images, etc. So, save it in a folder that contains the data you need (either in the same folder or in a subfolder).
🎉 Congrats! You are done with the boring part.
Outline an engaging document
I’m going to make a bet 🎲 .
I bet that you (painfully) learned that scientific writing starts with an introduction, which is followed by a description of the method, which is followed by a series of technical findings, which leads to a more substantive discussion of your findings.
Am I right?
Well, this outline only really works in the academic environment. Audiences outside academia struggle with this outline. Even in academia, people struggle to fit in their process writing (drafts, executive summaries, presentation outlines, etc.) into this outline. Unless your reader has blocked an hour and sits in a place without distractions, your odds of engaging your reader with a traditional outline are pretty small.
An outline that works
Let’s stand in the shoulders of giants. A few years ago, an amazing collaboration between members of the American Evaluation Association led to the Potent Presentations Initiative. The initiative offers lots of great advice on presenting results effectively. The one piece of advice that I keep coming back to is:
Start with the bottom line, then explain how you got there.
This outline was designed for presentations, but I’ve found that it works really well for documents too:
# Background
Brief introduction. Minimal background your audience needs to understand your main finding.
# Bottom Line
"Our main finding is that... This finding is important because..."
# Explanation
All the information your reader needs to understand how you arrived at your main finding.
Avoid too much detail; focus on the essential information your audience needs.
Use an appendix, supplement, or technical document for the rest.
# So What
Tell your audience all the reasons why your findings are important or useful.
Tie them back to what they care about.
# Call to Action
Invite your reader to act based on your finding.
The headings here illustrate the goal of each section, not the literal headings I want you to use in your documents. Remember:
Your ultimate goal while working as a researcher or data scientist is to communicate findings that contribute to making decisions.
So don’t get hung up on how much you enjoyed analyzing data or that fancy table you made. Focus on outlining documents that people are going to be excited to read and share.
🇪🇸 ¿Estás listo para desafiarte a ti mismo?
Empecemos con lo básico. Aquí, puedes aprender cómo crear un documento basado en plantillas existentes y cómo construir un documento interesante desde el principio.
Instalar el paquete {pagedown} 📦
El primer paso es asegurarte de que has instalado {pagedown} en tu máquina. Si no lo has hecho, entonces ejecuta esta línea de código en tu consola:
install.packages("pagedown")Comienza con una plantilla aburrida
Una vez que instales el 📦, tendrás acceso a una serie de plantillas. La plantilla thesis_paged es un excelente punto de partida si quieres escribir una tesis o disertación totalmente reproducible:
En estos días, a menudo creo informes internos y externos basados en la plantilla html_paged, que es la plantilla más genérica en el 📦:
Independientemente de la plantilla que elijas, cuando guardes la plantilla en algún lugar de tu computadora, recuerda que este documento será uno de muchos elementos en tu flujo de trabajo. Necesitas tener en cuenta que el documento necesita acceder a carpetas con datos, imágenes, etc. Por lo tanto, guárdalo en una carpeta que contenga los datos que necesitas (ya sea en la misma carpeta o en una subcarpeta).
🎉 ¡Felicidades! Ya terminaste con la parte aburrida.
Estructura un documento interesante
Voy a hacer una apuesta 🎲.
Apuesto a que aprendiste (dolorosamente) que la escritura científica comienza con una introducción, que es seguida por una descripción del método, que es seguida por una serie de hallazgos técnicos, que llevan a una discusión más sustantiva de tus hallazgos.
¿Estoy en lo correcto?
Bueno, este esquema solo funciona realmente en el entorno académico. Las audiencias fuera de la academia tienen problemas con este esquema. Incluso en la academia, las personas luchan por encajar su proceso de escritura (borradores, resúmenes ejecutivos, esquemas de presentación, etc.) en este esquema. A menos que tu lector haya bloqueado una hora y se siente en un lugar sin distracciones, tus probabilidades de involucrar a tu lector con un esquema tradicional son bastante pequeñas.
Un esquema que funciona
Pongámonos de pie en los hombros de gigantes. Hace unos años, una increíble colaboración entre miembros de la American Evaluation Association dio lugar a la Iniciativa de Presentaciones Potentes. La iniciativa ofrece un montón de buenos consejos sobre cómo presentar resultados de manera efectiva. El consejo al que siempre vuelvo es:
Comienza con la conclusión, luego explica cómo llegaste allí.
Este esquema fue diseñado para presentaciones, pero he descubierto que también funciona muy bien para documentos:
# Antecedentes
Breve introducción. Mínimo antecedente que tu audiencia necesita para entender tu hallazgo principal.
# Conclusión
"Nuestro hallazgo principal es que... Este hallazgo es importante porque..."
# Explicación
Toda la información que tu lector necesita para entender cómo llegaste a tu hallazgo principal.
Evita demasiados detalles; enfócate en la información esencial que tu audiencia necesita.
Usa un apéndice, suplemento, o documento técnico para el resto.
# ¿Y qué?
Dile a tu audiencia todas las razones por las que tus hallazgos son importantes o útiles.
Vincúlalos de nuevo con lo que les importa.
# Llamado a la Acción
Invita a tu lector a actuar en base a tu hallazgo.
Los encabezados aquí ilustran el objetivo de cada sección, no los encabezados literales que quiero que uses en tus documentos. Recuerda:
Tu objetivo final mientras trabajas como investigador o científico de datos es comunicar hallazgos que contribuyan a la toma de decisiones.
Así que no te obsesiones con cuánto disfrutaste analizando datos o esa elegante tabla que hiciste. Enfócate en estructurar documentos que la gente estará emocionada de leer y compartir.
Amazing article Diego! Super actionable, thanks!