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 all participants as a starting point. Participants will set up a GitHub repository that uses continuous integration to build a minimal website for their project and publish it to GitHub Pages. By the end of the workshop, participants will have further developed and customised their site for a bespoke and professional set of pages documenting their project in a best practice fashion.

Syllabus:

• Importance of documentation
• Overview of static site generation and GitHub Pages
• Setting up the static site generator
• Adding navigation and sections
• Configuring and deploying to GitHub Pages
• Setting up a GitHub Actions workflow
• Advanced customisation

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
• Understand best practices like docs-as-code and documentation-driven development
• Use a static site generator to render a set of Markdown files into a working website
• Automate the build process with GitHub Actions continuous integration
• Customise the look, feel and navigation of the generated pages

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, which you may use to explore the taught materials.

How to book

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

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