Co-Chair Contributor Experience at Kubernetes
One of the major properties of successful open source projects is their ability to be transparent with their communities. This involves everything from open governance, to values, to technical direction.
In the past, OSS projects didn’t have many options for tooling. The organized ones ran their own mailing lists and contributors to those projects seemingly spent as much time on their project infrastructure as they did on the projects themselves. As SaaS became more prevalent, the amount of options grew exponentially, but so did the complexity and choice overload.
Therefore when a simple, powertool comes along it can make an impression.
One of the things I’ve been doing for a few years is running a Kubernetes Office Hours. I also participate in TGIK, a livestream, and many of VMware’s Open Source projects. All of these require taking notes, working with a community of contributors, and then committing the notes somewhere for future reference.
Here’s how I ended up using HackMD across the board:
Markdown
Markdown is the lingua franca of OSS now. We write our READMEs in it. We write our docs with it and use wonderful tools like hugo to export really nice looking documentation and websites. Any tool I use needs to have this support built in.
- I can import/export anything to our GitHub repo and it just works.
- I can import/export anything to our Discourse forums and it just works.
- I can prototype documentation with a group of people and do all the commenting, review, and nitty gritty work in one document.
I used to prototype something in a Google Doc then send it to a list. Wait for a bunch of people to ask me for the right permissions, finally get all the reviews done, and then convert it to Markdown for a pull request.
Google docs are great for writing documents, but for technical content that will end up living in a repo, nothing beats native markdown and a git repository. Having native GitHub authentication makes this easy since people use the same accounts they use when reviewing the final content.
It’s easy for people to join in
Our TGIK podcast is a YouTube livestream with a live audience.
We use custom DNS so that our show notes are always at tgik.io/notes, this makes it easy and rememberable. Every episode we ask people to dive into the notes while the show is happening. YouTube’s chat functionality doesn’t allow for people to paste in links, and even if it did, there’s something to be said for making the audience put the show notes and URLs for things they find interesting in the notes directly.
It cleans up the chat and gives our audience a sense of ownership around the topic we’re discussing. The host prepares the notes ahead of time, and the audience fills in the gaps as the host is doing the demo and the actual show. This has also allowed us to build an archive as we went along which we can easily push to a git repository.
It’s fast
Not much to say here. :D
Anyone can use it (or not use it)
Everyone in the projects I work on use a GitHub account. It also supports other popular account methods. However a surprising feature is how it works when no one signs in at all. If they don’t want to sign in they don’t have to, I can make accounts that enforce a sign in or not, the option is up to me.
Here’s how it works as an example:
- I come up with a great idea, I immediately fire up a new page and start writing.
- I can send the link to the people I want to see it, and they can begin writing immediately.
- We decide if the idea is good I then quickly check the permissions to ensure they are correct and then share with a wider group.
The initial set of people I sent it to can begin writing immediately with zero friction.
When I mention “It’s fast” I don’t mean just the software itself. I mean the workflow.
Similarly, people who don’t use hackmd don’t need to see it.
Since it’s markdown-native you can happily just see the raw text when I PR it. You can review it in GitHub, you don’t need to care about the dozens of people who might have contributed to it, or all the comments I have addressed while drafting. I can do all of those things ahead of time before submitting a review.
- Is my submission too unfinished?
Easy, I close it and give you the hackmd link, then we go into deep review with comments, rewrites, and hardcore dissection. I can easily spit out another PR. It’s all just Markdown.
Sharing is easy
I can click one button and share the URL almost immediately. No digging into menus and no “Create link of this document?” to hide some unweildly URL. I share immediately and there’s 2 simple dropsdowns for permissions. I default to open for everything since when I’m drafting I want to be able to send a link to folks and have them dive right in.
Notice the custom field for the share name, I don’t need to use a URL shortener either, one less thing for me to worry about.
I can easily change the permissions at any time quickly via the share button.
Templates
Templating by itself is a simple feature. But if you haven’t guessed by now there’s lots of value in being able to share my notes templates with other projects.
I can reuse them in GitHub or Discourse, document them on my hugo page, and keep them all consistent. Again, by choosing Markdown as the language I can easily share across all my properties.
Exporting and Self Hosting
The usual basics are there, however, I want to talk about exporting in a more strategic manner than just “It can export to Dropbox”.
The ability to self host via CodiMD is crucial.
I don’t use this, part of the value for me is not being a system administrator, but having this as an option for folks is becoming rarer these days, but it is a crucial value that should be lauded. We also don’t host our own Discourse forums, but the root value of having self-hosted options is a nice guarantee from software that we use every day.
Conclusion
There are a bunch of features I haven’t even talked about yet (like using it for slidedecks). I use them on occasion but for my usage it’s all about the core workflow: Create, share, and then publish/commit.
