Introduction to Markdown for Communicating Software Projects

Writing code is only one aspect of software development. Communicating your work is crucial for others to find, understand, execute and contribute to your projects. This workshop will focus on this aspect of communication, using Markdown to create simple but attractive outputs that can, for example, become part of your GitHub repository. 

Markdown is a markup language for formatting text. Its easy-to-use syntax gives users the power to style and format text as they write. Markdown offers several elements that make it particularly well-suited to writing technical documentation, such as code highlighting, task lists, tables and more. Markdown is the language of choice for GitHub, Jupyter Notebooks and R Notebooks – each with its own flavour that extends the basic functionality of Markdown. 
 
In this workshop, we will explore Markdown’s basic syntax and usage and see some advanced features that are specific to the different flavours of Markdown. Participants are encouraged to bring their own GitHub repository, Jupyter Notebook, or R Notebook to the session, but mock resources will also be provided. By the end of the workshop, participants will be equipped with the knowledge and skills to create an attractive README, Jupyter Presentation, or R Markdown report. 

Syllabus:

• Why we communicate code and software
• Basic Markdown syntax, images, and links 
• Markdown tables and code blocks
• GitHub-flavoured Markdown (task lists, admonitions, math formatting, diagrams)
• Create communicable outputs with Markdown in GitHub, Jupyter or R

Important - You must have a GitHub account that you can access during the session. You are encouraged to bring a project that you are working on (Jupyter or R Notebook, or code in a GitHub repository). A sample project will be provided for participants who do not bring a project.

Learning Outcomes:

On completion of this workshop you will be able to:

• Create communication outputs for code or software projects that you develop
• Format text, create tables, and insert images and code blocks using Markdown
• Utilise advanced Markdown syntax offered by GitHub’s flavour of Markdown
• Create a README, a Jupyter presentation or an R Markdown report
  
  

Dates & Booking Information

• Monday 18 November 2024, 14:00-16:30, South Kensington (In-Person Teaching)

To book your place, please follow the booking process advertised on the main programme page