Further Website Development for Software Projects

“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

This course is open to Research Degree Students, Postdocs & Research Fellows. Limited spaces available for wider Imperial community.

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

Prerequisites

You must have a GitHub account that you can access during the session. Prior knowledge of GitHub and Markdown is helpful, for which we can recommend taking our Introduction to Creating a Website with GitHub and Markdown course (for credit).

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.

How to book

• Early Career Researchers (Research Degree Students, Postdocs, Research Fellows) should book via Inkpath using your Imperial Single-Sign-On.
• All other members of the Imperial community, should book here.

Please ensure you have read and understood ECRI’s cancellation policy before booking.