Publishing Software Projects for Open Science

“if a feature isn’t documented, it doesn’t exist” - unknown

 A piece of software is only as good as its documentation. Documentation is the human-readable accompaniment to code. Much more than just in-line comments for other developers, the holistic view of documentation looks to support all the stakeholders that contribute to or rely on your code. Open science is a key aspect of your research, and online documentation is one step towards ensuring that others understand how your code works and how they can use it. Publishing your documentation and maintaining it for the world to see demonstrates transparency and accountability in your work. It will also provide a smart and efficient way to share and disseminate your work.

In this workshop, participants will apply best practices and modern frameworks to create a website for their code or software project. Participants are encouraged to come prepared with a research computing or data science project of theirs that they wish to share publicly. A mock project will be provided for participants without a project of their own. Participants will set up a GitHub repository that uses continuous integration to build a minimal MkDocs site for their project and publish it to GitHub Pages. By the end of the workshop, participants will have further developed and customised their MkDocs site for a bespoke and professional set of pages documenting their project in a best practice fashion.

Syllabus:

• Importance of documentation
• Overview of MkDocs and GitHub Pages
• Setting up Material for MkDocs
• Adding navigation and sections
• Configuring and deploying to GitHub Pages
• Setting up a GitHub Actions workflow for MkDocs
• Advanced customisation of Material for MkDocs

Important - You must have a GitHub account that you can access during the session. You are encouraged to bring a code or software project that you are working on, for which you would like to create and publish a webpage. 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:

• Appreciate and produce high quality, accessible, and readable documentation
• Use Material for MkDocs to render a set of Markdown files into a working website
• Automate the MkDocs build process with GitHub Actions continuous integration
• Customise the look, feel and navigation of the generated MkDocs pages
• Understand best practices like tutorial-based and documentation-driven development
  
  

Dates & Booking Information

• Thursday 21 November 2024, 10:00-12:30, South Kensington (In-Person Teaching)

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