I am one of the primary managers of my company’s public github site. While we generate a lot of code, most of this work is not designed to be shareable (run once or twice for a particular project and then move on to the next project) as the focus is on the research work. For most people, a programming language is just a tool to solve some big problem — identify a cohort of people, generate statistics, build tables for a paper, etc. Quite rightly, in my opinion, there is an increasing effort to make this code publicly available so that:
- others can use it (where others might include your future self), and
- increase transparency of methods.
This push is useful (albeit it can result in citationware if the paper/publication reviewers don’t really know what they’re doing), but many programmers are unsure exactly how to get started sharing their code or publicizing their work. One brilliant statistician I work with described GitHub as a place where they drag their code files over when writing a publication. This is a good first step…and while I would love to convince this cohort of research, data, and statistical specialists (who mostly write code) that git should be a close ally and friend, they don’t really see its advantages (yet).
In addition to GitHub being a place to ‘drag code’ when writing a publication, there is also growing interest in making use of it as a platform to conveniently aggregate and advertise work being done. Sure, I have a few scattered repositories, but I’d like to have a page where I can advertise all the work that my working group has accomplished. My company has public portals, but these have a number of gatekeepers and require special access, approval processes, and the joy of html, css, or whatever javascript framework you like. No, instead a site that I can manage and update would be much more ideal.
In response to such requests, I recommended trying out GitHub pages. GitHub pages is simple to get setup, can be written in markdown, and will automatically update — all perfect for non-experts. On our company GitHub organisation, I created a new team and added the users to it (once they’d all at least signed up as GitHub users), setting their working group heads as ‘admins’ (well, maintainers roles).
Next, I created a new repository with a short, catchy name (this will be the stub at company.github.io/catchy-name). With GitHub pages, you can create the site at the root of the project, but this doesn’t seem like a great idea — where would the instructions, supporting files, etc. be placed? I quite dislike having so many items at the root of the project if it can be avoided. If you don’t want your site files at root, your only other option is to place them in a docs/ subdirectory. I created this project structure:
README.md: instructions for users on how to update the site, what it’s purpose is, etc.docs/: web-root_config.yml: GitHub pages configuration file (see below)index.md: ‘markdown’ file which will be the ‘Home page’work.md: a page documenting code repositories and publicationscontact.md: a page mentioning how to contact the group for work, resources, etc.resources.md: resources that have been made available by the group
The _config.yml file contains some basic configurations, including a theme (i.e., how the pages will look), type of markdown to use, and a title and description.
title: Name of the Group
description: A description that will appear at the top
theme: jekyll-theme-slate
markdown: gfm
show_downloads: false
github:
is_project_page: falseBy default, a number of these themes will display a View on GitHub button, which I didn’t want, especially as the repository itself is private. The last two lines (github.is_project_page: false) will remove it.
That’s all we need! I pushed this repository and then went into the repository settings. There’s a ‘pages’ settings page where I enabled pages and set the files to be served from the docs directory. Any changes that are pushed to the main branch will trigger a site rebuild (you can follow along in the Actions tab):
Now, the users can access the already-built site here: company.github.io/catchy-name, and then make easy edits using the GitHub interface by directly editing the already-created markdown files. I also added navigation for all of these sites and placed it across the top of each:
[Home](index.md) · [Resources](resources.md) · [Projects](work.md) · [Contact](contact.md)