A situation probably everyone of us has run into:
I have knowledge, and I want to share and let people contribute to it, too. Classic use case for GitHub, isn't it? But then, how to say it without offence, GitHub isn't the most welcoming place for non-techies, right? It's not the go-to platform for people who are looking for knowledge apart from code. I think it's even realistic to assume that people who aren't using GitHub at least a few times a year are skipping on search results that have github.com in their url.
For me, this became even more of a problem when I started doing program management. There was internal wikis, where I could document our processes, strategies and policies, but as soon as I wanted to share and ask for contributions in public, I defaulted to using GitHub. Even though I was aware I'd create content that was only accessible to techies.
When I started working on career ladders for, admittedly, tech roles in our Open Source Program Office at Postman, I wanted it to be public. And I wanted it to have an impact on the industry. Because personal development is important. And too few people, managers as well as individual contributors, care about it. To help this make an impact I'd need to reach people outside of engineering teams, so this documentation could not be a README.md, hidden somewhere in a repo. I wanted it to be at least a website. One like https://career-ladders.dev.
I read into GitHub Pages, as I've heard from it before, but hadn't yet used it. I was very conscious that I missed out on one of those obvious features from the platform so long. And it embarrassed and still embarrasses me. Like I've also never used CoPilot. Never too late, they say. 🤷‍♂️
Here's what you have to do to make your markdown files convert to a website (full documentation):
1) have at least the README.md markdown file in a dedicated public repo
2) go to "Pages" through the repo's Settings -> Code and automation
3) use Source -> Deploy from a branch, and Branch -> "main" -> Save, for the simplest setup.
4) wait for the Action to finish. Can take up to a few minutes.
5) visit your page at org-name.github.io/repo-name
If you want to use only a subdomain (the part before github.io) and no appended folder name, your repo must be named <user>.github.io or <organization>.github.io.
I find the Pages representation of a repo helpful in many ways.
As a former web developer, I instantly see what information is missing. No images, not enough links, lack of description, how to navigate this? It's much harder for me to identify these missing pieces in the GitHub repo.
Having a website makes many people outside your bubble more likely to read your content.
Your project suddenly feels more important and real.
You learn because right now your page looks super shitty. This is the moment when you invest more time into learning how to choose a theme and re-work the structure of your markdown files. This is where to start.
If you want to learn more about my career ladders work, visit the repo on GitHub.
And these are the GitHub Pages for the Open Source Contributor and OSPO Engineer Career Path. You see I still have to improve a lot of things for that last "your page looks super shitty" part.
Top comments (0)