What If GitHub Projects Were As Beautiful as Medium Articles?

By Marc Howard

Imagine that you are a coder with a brilliant idea for the next billion dollar tech startup. You have even coded-up a proof-of-concept but then realize that you are in over your head. There are bugs, you’re pressed for time since this is just a side-gig, and you’re frustrated with asking question after question on coding forums.

This was me…and I am not a coder.

Enter Github, a free web platform for uploading, sharing and collaboratively working on open-source code. It even let’s you version control and make your project private if you like. One would think that this is the perfect solution to getting your project from 0 to 1. But its ugly.

The problem is that many projects on Github, despite being run by some of the best coders, simply do not get the visibility and traction to become something great. Just like the billions of abandoned webpages littering the internet today, Github project repositories are mostly in this same sorry state of disarray.

If you have a brilliant idea for a tech project or startup and want to give it the attention and collaborative development to make it a working product, Github can be your new best friend. Or you can end up hating it.

I work with developers everyday, many of who have an open-source project on Github. I’ve come to notice that many of their ideas are great, coded by some truly creative minds. The problem is that no one sees it.

Having written a plethora of articles here on Medium I have come to love the easy, no-HTML-code-required writing that handles all of the formatting, media, topic tagging, publishing, social sharing and syndication of this platform. You can even leave a reply to an article and publish that a Medium post (if you haven’t created a Medium post yet, that was your queue).

When you want to create a Github project or “repository” you can optionally create a Readme file to explain to the world what your project is all about. Its ugly and nothing like the Medium experience. Most coders create projects on Github because they want others to help and coolaborate. Unfortuntely many projects look very similar to this one:

One of millions of lonely projects on Github.

As of today there are almost 100 million project repositories on Github. If you are seeking to help on a project or find others to help on your project, the above example is not exactly the most inspiring. It doesn’t even have a Readme file to introduce the project, the goals, the milestones or even explain what the code is about. Here’s another vague project for a “chatbot” which does not even have a description:

Compare this to some of the more well documented projects. The following project not only has a Readme but includes graphics, a structured layout and even examples:

My project, Algohive aims to build on these best practices for styling and documentation. I did need to learn a lightweight styling syntax called Markdown. All said and done, even a non-coder like myself was able to figure it out without too much fuss:

Hint: If you click on “Fork” in this repository you can copy the entire thing as-is as a template to make your own!

Markdown is pretty simple actually and lets you do many things that a Medium article allows for better visualization. I was able to go from no Markdown coding to the above Github repository in just a couple of hours.

If you really want to get fancy (or you’re simple seeking to keep you sanity) you can also create a a kanban-style project in Github. While not perfect, its a great free light-weight alternative to many product management apps like Jira. Here’s what a Github project board looks like:

Github project board

To get up to speed and learn Github and Markdown quickly two excellent free resources are the Github Guides and Dillinger WYSIWYG editor. There are still a few one-off hassles though. Creating a table originally almost gave me an ulcer until I came across the Table Magic convertor that now lets me sleep better at night.

Most Github project overviews are ugly and nothing like the Medium experience.

Many of my friends these days are coders. Coders like to code, not spend time on styling and detailed documentation. I totally get it. This is why I believe that a two-hour investment in learning Markdown could be just as valuable to the dozens of hours that you’ve used to code-up that next tech unicorn. The point is that if you want help, make it easy for other great coders (and non-coders like me) to find you and collaborate.

Why is this important? If your project is one the of millions of projects littering Github with no recent updates, collaborators or general activity chances are it does not have a clear Readme or a project overview. Yes, you can certainly leave comments directly in your code but — come on, how many want to dive that deep and spend the time to try to figure out what you’ve hacked together?

At Algohive we’re crowdsourcing the development of cryptocurrency prediction algorithms using machine learning. The last thing I want for new members to our community to do is to have to figure out what the project is all about. Onboarding and user experience (UX)is integrated throughout our Github repository to our website to our Discord community.

We’ve learned that while its helpful to be a coder or machine learning practitioner, we also need the skills of the best crypto traders, data analysis and investors. In other words if you can’t code then you can still contribute through our community chat forum on Discord as we crowdsource intelligence to build and launch our crypto trading bots.

From a growth perspective Github now brings in almost as many new members as our website and blog articles. This is important because we attract members where they already hang out. Looking for an great coder or collaborator? You’ll find many on Github, which even has a profile section to reach out directly or to see what cool projects that they are already involved with:

Another important take home point is that if you’re using Github as a portfolio of projects for a new job interview or seeking to get the attention of angel investors its a win-win.

There will always be better coders and being the best coder in the world isn’t helpful if no one knows it. How many coders also are articulate, meticulous with documentation and understand the importance of personal branding? Not many but these are the true unicorns among us.

While Github markdown takes some getting used to its well worth the investment. Take this opportunity to one-up your game and be known not only as a wicked-smart coder but also as a future founder who knows how to attract the right talent and attention to your work.

If you happen to write Medium articles about your work then why not apply those skills to your project on Github? Conversely if you write a killer Readme in Github, why not use those very transferable skills to write an article about it in Github? The sky’s the limit. Remember: If you don’t build it, they will never come.

So what if Github and Medium did meet and have a baby? Who knows — but at least its now an idea pregnant with possibility.

If you found this article to be helpful please Clap (up to 50 times) and share to help get it in front of more people so they too can up their game. If you would like to get the latest updates on our project please follow me here on Medium. If you want to be a part of Project AlgoHive, a crowdsourced cryptocurrency prediction startup you can learn more here.