Literate programming chapter?

[AndreaSanchezTapia]

Summary

• What is the name and purpose of your chapter? Literate programming

• Why are you proposing it? Because literate programming is a crucial tool to support open research. We could discuss tools and workflows, LaTeX and markdown but also rmarkdown, pythonbook, overleaf, and related resources. Maybe point towards reproducible manuscript submission using Latex templates and share tips of workflows (because being able to insert code in your documents sounds awesome but is not necessarily a good idea and a thing you want to do all the time).

• What Guide is the chapter for? I'd say the Communication guide, around the section about the types of papers than can be published.

• What branch are you working on? (no branch for now but happy to create one and see if others have thought of related content, I will update the issue accordingly 😇 )

Discussion Points

• What would be encompassed? It can start with markdown as lingua franca but build towards rmarkdown, pyhtonbook, LaTeX and Sweave... Also: workflows and folder structures when writing reproducible manuscripts.

Who can help?

Anyone

Updates

• Quick discussion about the relevance and scope (here now 2022-08-08)
• Write chapter outline
• Add material to the chapter
• Combine materials into a readable chapter
• Proofread
• Request reviews
• Address reviews
• Merge to main branch.

[welcome]

🎉 Welcome to The Turing Way! 🎉 We're really excited to have your input into the project! 💖

If you haven't done so already, please make sure you check out our Contributing Guidelines and Code of Conduct. If you need to connect more synchronously with members of The Turing Way community, please feel free to chat with us in our Slack workspace, or you can join our Collaboration Cafe for mentored contribution or co-working.

[jcolomb]

is "literate programming" a synonym of "executable papers" ? I am not sure about the term meaning...

quarto and stencils seem to be the most advanced tools for that (?)

[BeastyBlacksmith]

is "literate programming" a synonym of "executable papers" ?

Yeah, meaning of this term shifted a bit over the years from "writing code and documentation in the same document" to "writing files that contain text as well as code and being able to convert that to different output formats"

[BeastyBlacksmith]

I got some slides from a course named "Reproducible scientific computing" that I gave last year (pre quarto), that I attach here.
LiterateProgramming.pdf

[AndreaSanchezTapia]

Yes, literate programming would be similar to "write texts and compile code simultaneously" but about the chapter, I think it could talk in general about how to write research reports/manuscripts/documentation in a reproducible way and after a section that includes plain markdown, latex, and other text-based options (that allow version control), talk about literate programming.

[hlapp]

I have been teaching and promoting literate programming and corresponding methodologies under the Reproducible Science umbrella (the concept of interweaving research narrative and questions with the code that implements said questions, figures and other output generated by said code, and summary and interpretation of said outputs). More generally, it's one way to create "executable papers" (e.g., Lasser (2020)).

[aleesteele]

Hi all! Just dropping in to add in an all-contributors tag, don't mind me. I'm excited to follow this chapter as it develops, sounds like there are lots of folks that can help Andrea to scaffold a structure. Happy to review from an outsider's perspective for clarity, etc as it develops.

@all-contributors please add @AndreaSanchezTapia for ideas

[allcontributors]

@aleesteele

I could not determine your intention.

Basic usage: @all-contributors please add @Someone for code, doc and infra

For other usages see the documentation

[aleesteele]

@all-contributors please add @AndreaSanchezTapia for ideas

[allcontributors]

@aleesteele

@AndreaSanchezTapia already contributed before to ideas

[andreaczhang]

I would like to pick up this issue!